Merge pull request #57 from omnifed/56-docs-add-usetheme-reference

56 docs add usetheme reference

docs/app/components/Nav.tsx

@@ -21,10 +21,14 @@ export function Nav() {
   return (
     <nav
       className={grid({
+        backdropFilter: 'blur(20px)',
+        backdropBlur: 'md',
         alignItems: 'center',
         columns: 3,
         gridTemplateRows: '1fr 1fr',
         gap: '0',
+        mb: '12',
+        position: 'sticky',
         md: {
           gridTemplateRows: '1fr',
           pxi: '6',

docs/app/components/PageLayout.tsx

@@ -2,16 +2,18 @@ import type { PropsWithChildren } from 'react'
 import { grid, gridItem } from '@/styled-system/patterns'
 import { markdown } from '../styles/markdown'
 
+const PAGE_MINUS_HEADER = 'calc(100dvh - 9.5rem)'
+
 interface PageLayoutProps {}
 
 export function PageLayout(props: PropsWithChildren<PageLayoutProps>) {
   return (
     <div
       className={grid({
         columns: 12,
+        h: PAGE_MINUS_HEADER,
         overflowX: 'hidden',
         position: 'relative',
-        pt: '12',
         md: {
           overflowX: 'initial',
         },
@@ -26,7 +28,7 @@ export function PageSideNav(props: PropsWithChildren<PageLayoutProps>) {
   return (
     <div
       className={gridItem({
-        h: '100dvh',
+        h: PAGE_MINUS_HEADER,
         position: 'fixed',
         top: 0,
         left: 0,
@@ -55,6 +57,9 @@ export function PageMainContent(props: PropsWithChildren<PageLayoutProps>) {
       className={gridItem({
         gridColumnStart: 1,
         gridColumnEnd: 13,
+        overflowY: 'auto',
+        pb: '12',
+        scrollBehavior: 'smooth',
         md: {
           gridColumnStart: 3,
           gridColumnEnd: 11,

docs/app/global.d.ts

@@ -0,0 +1 @@
+declare module 'color-space'

docs/app/layout.tsx

@@ -5,7 +5,6 @@ import { ThemeProvider } from '@cerberus-design/react'
 import { css, cx } from '@/styled-system/css'
 import { Nav } from './components/Nav'
 
-import './two-slash.css'
 import './globals.css'
 
 const poppins = Poppins({

docs/app/preset/colors/components/ColorSwatch.tsx

@@ -6,6 +6,7 @@ import { useEffect, useMemo, useState } from 'react'
 import { css, cx } from '@/styled-system/css'
 import { hstack, vstack } from '@/styled-system/patterns'
 import { Checkmark } from '@cerberus-design/icons'
+import { hasWhiteBase } from '@/app/utils/colors'
 
 // TODO: Figure out how to validate color contrast a11y for text on background
 
@@ -39,6 +40,27 @@ const noPB = css({
   },
 })
 
+const inverseTextStyles = css({
+  '&[data-palette="neutral"]': {
+    color: 'neutral.text.inverse !important',
+  },
+  '&[data-palette="action"]': {
+    color: 'action.text.inverse !important',
+  },
+  '&[data-palette="info"]': {
+    color: 'info.text.inverse !important',
+  },
+  '&[data-palette="success"]': {
+    color: 'success.text.inverse !important',
+  },
+  '&[data-palette="warning"]': {
+    color: 'warning.text.inverse !important',
+  },
+  '&[data-palette="danger"]': {
+    color: 'danger.text.inverse !important',
+  },
+})
+
 export default function ColorSwatch(props: ColorSwatchProps) {
   const { _cerberusTheme } = props.token.value
   const { mode } = useThemeContext()
@@ -48,6 +70,12 @@ export default function ColorSwatch(props: ColorSwatchProps) {
     return mode === 'dark' ? '_darkMode' : '_lightMode'
   }, [mode])
   const color = _cerberusTheme[modeValue]
+  const swatchStyles = useMemo(() => {
+    if (hasWhiteBase(color, mode)) {
+      return cx(noPB, inverseTextStyles)
+    }
+    return noPB
+  }, [color, mode])
   const bgColor = {
     backgroundColor: color,
   }
@@ -99,7 +127,7 @@ export default function ColorSwatch(props: ColorSwatchProps) {
         </span>
       )}
       <div>
-        <p data-palette={props.palette} className={noPB}>
+        <p data-palette={props.palette} className={swatchStyles}>
           {props.tokenName}
         </p>
         <p
@@ -108,7 +136,7 @@ export default function ColorSwatch(props: ColorSwatchProps) {
             css({
               textTransform: 'uppercase',
             }),
-            noPB,
+            swatchStyles,
           )}
         >
           {color}

docs/app/preset/overview.mdx

@@ -23,9 +23,7 @@ pnpm install @cerberus-design/panda-preset
 
 Once you have installed and setup Panda CSS and added the Cerberus Panda Preset, you need to update your Panda configuration to include the Cerberus Panda Preset.
 
-Update your `panda.config.ts` file to include the Cerberus Panda Preset:
-
-```ts twoslash
+```ts title="panda.config.ts"
 import { defineConfig } from '@pandacss/dev'
 import pandaPreset from '@pandacss/preset-panda'
 import { cerberusPreset, cerberusConfig } from '@cerberus-design/panda-preset'
@@ -54,7 +52,7 @@ If you would like to use the Brand font associated with Cerberus, we recommend P
 
 NextJS usage:
 
-```ts twoslash
+```ts title="app/layout.tsx"
 import { Poppins } from 'next/font/google'
 
 const poppins = Poppins({
@@ -76,7 +74,7 @@ pnpm add @cerberus-design/{react,icons}
 
 To help make maintaining a breeze, add this new script to your `package.json` to use when you are ready to upgrade Cerberus:
 
-```json
+```json title="package.json"
 "scripts": {
   "up:cerberus": "pnpm up @cerberus-design/{panda-preset,react,icons}"
 }

docs/app/react/layout.tsx

@@ -1,22 +1,25 @@
 import type { PropsWithChildren } from 'react'
-import { cx } from '@/styled-system/css'
-import { container } from '@/styled-system/patterns'
-import { markdown } from '../styles/markdown'
+import {
+  PageLayout,
+  PageMainContent,
+  PageSideNav,
+  PageSections,
+} from '../components/PageLayout'
+import SideNav, { type NavList } from '../components/SideNav'
+import sideNavData from './side-nav.json'
 
 interface ReactProps {}
 
 export default function ReactLayout(props: PropsWithChildren<ReactProps>) {
   return (
-    <div
-      className={cx(
-        container({
-          pt: '12',
-        }),
-        markdown,
-      )}
-    >
-      <header>Nav sidebar</header>
-      {props.children}
-    </div>
+    <PageLayout>
+      <PageSideNav>
+        <SideNav navList={sideNavData as NavList} />
+      </PageSideNav>
+
+      <PageMainContent>{props.children}</PageMainContent>
+
+      <PageSections>On this page</PageSections>
+    </PageLayout>
   )
 }

docs/app/react/overview.mdx

@@ -22,3 +22,7 @@ Install the Cerberus React library, with the package manager of your choice:
 ```bash
 pnpm install '@cerberus-design/react'
 ```
+
+## Typescript
+
+The Cerberus React library is written in TypeScript and includes type definitions for all components.

docs/app/react/page.tsx

@@ -1,13 +1,8 @@
-import { css } from '@/styled-system/css'
 import Overview from './overview.mdx'
 
 export default function ReactPage() {
   return (
-    <main
-      className={css({
-        py: '6',
-      })}
-    >
+    <main>
       <Overview />
     </main>
   )

docs/app/react/side-nav.json

@@ -0,0 +1,41 @@
+[
+  {
+    "id": "1",
+    "label": "Overview",
+    "type": "heading"
+  },
+  {
+    "id": "1:a",
+    "label": "Installation",
+    "route": "/react",
+    "type": "route"
+  },
+  {
+    "id": "2",
+    "label": "Components",
+    "type": "heading"
+  },
+  {
+    "id": "2:a",
+    "label": "Button",
+    "route": "/react/button",
+    "type": "route"
+  },
+  {
+    "id": "3",
+    "label": "Hooks",
+    "type": "heading"
+  },
+  {
+    "id": "3:a",
+    "label": "useTheme",
+    "route": "/react/use-theme",
+    "type": "route"
+  },
+  {
+    "id": "3:b",
+    "label": "useThemeContext",
+    "route": "/react/use-theme-context",
+    "type": "route"
+  }
+]

docs/app/react/use-theme-context/doc.mdx

@@ -0,0 +1,96 @@
+import { Admonition } from '@/app/components/Admonition'
+
+# useThemeContext
+
+The `useThemeContext` hook allows you to access or modify the theme and mode properties of the Cerberus Design System in multiple components.
+
+```ts showLineNumbers=false
+type DefaultThemes = 'cerberus'
+type ColorModes = 'light' | 'dark'
+
+define function useThemeContext(
+  defaultTheme: DefaultThemes = 'cerberus',
+  defaultColorMode: ColorModes = 'light',
+): {
+  theme: DefaultThemes
+  mode: ColorModes
+  updateTheme: (theme: DefaultThemes) => void
+  updateMode: (mode: ColorModes) => void
+}
+```
+
+<Admonition
+  heading="When to use"
+  description="This hook is ideal for when you need to access or modify the theme or mode properties of the Cerberus Design System in multiple components."
+/>
+
+## Usage
+
+To use the `useThemeContext` hook, you need to wrap the component using the hook with the Cerberus `ThemeProvider` component.
+
+```tsx title="nav.tsx" {4}
+import { ThemeProvider, useThemeContext } from '@cerberus-design/react'
+
+function Nav() {
+  const { theme, mode, udpateTheme, updateMode } = useThemeContext()
+
+  function handleSetTheme(theme: string) {
+    updateTheme('party-town')
+  }
+
+  function handleToggleMode() {
+    updateMode((prev) => (prev === 'light' ? 'dark' : 'light'))
+  }
+
+  return (
+    <nav>
+      <button onClick={handleSetTheme} type="button">
+        update theme to party-town
+      </button>
+      <button onClick={handleToggleMode} type="button">
+        toggle mode
+      </button>
+    </nav>
+  )
+}
+```
+
+```tsx title="header.tsx" {4}
+import { ThemeProvider, useThemeContext } from '@cerberus-design/react'
+
+function Header() {
+  const { mode } = useThemeContext()
+
+  return (
+    <h1>
+      {mode === 'light' ? 'Hey, friend!' : 'I wear my sunglasses at night.'}
+    </h1>
+  )
+}
+```
+
+```tsx title="layout.tsx" {7}
+import { ThemeProvider } from '@cerberus-design/react'
+import Header from './header'
+import Nav from './nav'
+
+function Layout() {
+  return (
+    <ThemeProvider>
+      <Nav />
+      <Header />
+    </ThemeProvider>
+  )
+}
+```
+
+<Admonition
+  heading="When not to use"
+  description="When you need to access or modify the theme or mode proprties in a single component, consider using the `useTheme` hook instead."
+/>
+
+## API
+
+### Arguments
+
+The `useThemeContext` hook accepts the same arguments as the [useTheme hook](/react/use-theme).

docs/app/react/use-theme-context/page.tsx

@@ -0,0 +1,5 @@
+import UseThemeDoc from './doc.mdx'
+
+export default function UseThemePage() {
+  return <UseThemeDoc />
+}