@moises.ai/design-system 3.5.7 → 3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moises.ai/design-system",
-  "version": "3.5.7",
+  "version": "3.6.0",
   "description": "Design System package based on @radix-ui/themes with custom defaults",
   "private": false,
   "type": "module",
@@ -72,7 +72,8 @@
     "react-dom": "^19.0.0",
     "storybook": "^8.6.14",
     "vite": "^5.1.0",
-    "vite-plugin-css-injected-by-js": "^3.5.2"
+    "vite-plugin-css-injected-by-js": "^3.5.2",
+    "zod": "^4.3.6"
   },
   "publishConfig": {
     "access": "public"

package/src/components/Extension/Extension.jsx

@@ -0,0 +1,317 @@
+import { Children, createContext, useCallback, useContext, useMemo, useRef, useState } from 'react'
+import { Flex, Heading, IconButton } from '../../index'
+import { ArrowLeftIcon, Cross1Icon } from '../../icons'
+
+const ExtensionContext = createContext(null)
+const NavigationContext = createContext(null)
+const ScreenContext = createContext(null)
+
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the `moises` object from the nearest `<Extension>` ancestor.
+ * @returns {object} The moises extension API instance.
+ */
+export function useExtension() {
+    return useContext(ExtensionContext)
+}
+
+/**
+ * Stack-level navigation controls.
+ * Works anywhere inside an `<Extension>` with `initialScreen`.
+ */
+export function useNavigation() {
+    const ctx = useContext(NavigationContext)
+    if (!ctx) throw new Error('useNavigation must be used inside an <Extension> with initialScreen')
+    return ctx
+}
+
+/**
+ * Screen-specific context (name, params, setOptions).
+ * Only available inside a component rendered by `<Extension.Screen>`.
+ */
+export function useScreen() {
+    const ctx = useContext(ScreenContext)
+    if (!ctx) throw new Error('useScreen must be used inside an <Extension.Screen> component')
+    return ctx
+}
+
+// ---------------------------------------------------------------------------
+// Sub-components
+// ---------------------------------------------------------------------------
+
+/**
+ * Fixed header bar pinned to the top of the extension panel.
+ *
+ * @param {object} props
+ * @param {string} props.title - Heading text displayed in the header.
+ * @param {Function} [props.onBack] - Callback fired when the back button is clicked.
+ *   When provided, an arrow-left `IconButton` is rendered on the left side.
+ * @param {React.ReactNode} [props.headerLeft] - Custom left-side content. Replaces the
+ *   default back button when provided (even as `null`).
+ * @param {React.ReactNode} [props.headerRight] - Right-side action content. Takes priority
+ *   over `children` when both are provided.
+ * @param {boolean} [props.allowClose=true] - Whether to show the close (x) button on the right.
+ * @param {Function} [props.onClose] - Custom close handler. Defaults to `moises.extension.close()`.
+ * @param {React.ReactNode} [props.children] - Action elements rendered between the title and the close button.
+ */
+function Header({ title, onBack, headerLeft, headerRight, allowClose = true, onClose, children }) {
+    const moises = useContext(ExtensionContext)
+
+    const handleClose = onClose || (() => moises?.extension?.close?.())
+    const rightContent = headerRight ?? children
+
+    return (
+        <Flex
+            align="center"
+            gap="1"
+            mx="4"
+            py="3"
+            style={{ borderBottom: '1px solid var(--gray-a4)' }}
+        >
+            {headerLeft !== undefined ? (
+                headerLeft
+            ) : onBack ? (
+                <IconButton variant="ghost" color="gray" size="1" onClick={onBack}>
+                    <ArrowLeftIcon />
+                </IconButton>
+            ) : null}
+            <Flex align="center" gap="2" width="100%" style={{ flex: 2 }}>
+                <Heading
+                    size="3"
+                    weight="medium"
+                    style={{ width: '100%', minWidth: 0 }}
+                    trim="both"
+                >
+                    {title}
+                </Heading>
+            </Flex>
+            {rightContent && (
+                <Flex align="center" gap="1" justify="end" style={{ flex: 1, flexShrink: 0 }}>
+                    {rightContent}
+                </Flex>
+            )}
+            {allowClose && (
+                <IconButton variant="ghost" color="gray" size="1" onClick={handleClose}>
+                    <Cross1Icon />
+                </IconButton>
+            )}
+        </Flex>
+    )
+}
+
+/**
+ * Scrollable content area that fills all remaining vertical space.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} props.children - Content to render inside the scrollable area.
+ */
+function Content({ children }) {
+    return (
+        <div style={{ flex: 1, minHeight: 0, overflowY: 'auto' }}>
+            <Flex direction="column" p="4" gap="3">
+                {children}
+            </Flex>
+        </div>
+    )
+}
+
+/**
+ * Fixed footer bar pinned to the bottom of the extension panel.
+ * Only renders when children are provided.
+ *
+ * @param {object} props
+ * @param {React.ReactNode} [props.children] - Footer content (e.g. action buttons).
+ */
+function Footer({ children }) {
+    if (!children) return null
+
+    return (
+        <Flex
+            align="center"
+            justify="center"
+            mx="4"
+            py="3"
+        >
+            {children}
+        </Flex>
+    )
+}
+
+/**
+ * Declarative screen registration. Renders nothing — the navigator
+ * controls mounting based on the active stack.
+ *
+ * @param {object} props
+ * @param {string} props.name - Unique screen identifier for navigation.
+ * @param {string} props.title - Default header title.
+ * @param {React.ComponentType} props.component - Component to render when active.
+ * @param {React.ReactNode} [props.headerRight] - Default right-side header content.
+ * @param {React.ReactNode} [props.headerLeft] - Override for the default back button.
+ * @param {boolean} [props.allowClose=true] - Whether to show the close (x) button.
+ * @param {Function} [props.onClose] - Custom close handler.
+ */
+function Screen() {
+    return null
+}
+
+// ---------------------------------------------------------------------------
+// Navigator (internal)
+// ---------------------------------------------------------------------------
+
+const ANIM_DURATION = 200
+const ANIM_DISTANCE = 80
+
+function animateTransition(el, direction) {
+    if (!el) return
+    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches
+    el.getAnimations().forEach((a) => a.cancel())
+    const x = direction === 'forward' ? ANIM_DISTANCE : -ANIM_DISTANCE
+    el.animate(
+        [
+            { opacity: 0, transform: `translateX(${x}px)` },
+            { opacity: 1, transform: 'translateX(0)' },
+        ],
+        { duration: reduced ? 150 : ANIM_DURATION, easing: 'ease-out' },
+    )
+}
+
+function Navigator({ initialScreen, animated, children }) {
+    const [stack, setStack] = useState([{ name: initialScreen, params: {} }])
+    const [screenOptions, setScreenOptions] = useState({})
+    const [gen, setGen] = useState(0)
+    const stackRef = useRef(stack)
+    const wrapperRef = useRef(null)
+    stackRef.current = stack
+
+    const screens = useMemo(() => {
+        const map = {}
+        Children.forEach(children, (child) => {
+            if (child?.type === Screen) map[child.props.name] = child.props
+        })
+        return map
+    }, [children])
+
+    const navigate = useCallback((updater, dir = null) => {
+        if (animated && dir) animateTransition(wrapperRef.current, dir)
+        setStack(updater)
+        setScreenOptions({})
+        setGen((g) => g + 1)
+    }, [animated])
+
+    const push = useCallback(
+        (name, params = {}) => navigate((prev) => [...prev, { name, params }], 'forward'),
+        [navigate],
+    )
+
+    const pop = useCallback(
+        () => navigate((prev) => (prev.length > 1 ? prev.slice(0, -1) : prev), 'back'),
+        [navigate],
+    )
+
+    const popTo = useCallback(
+        (name) =>
+            navigate((prev) => {
+                const idx = prev.findIndex((e) => e.name === name)
+                if (idx === -1) throw new Error(`Screen "${name}" is not in the stack`)
+                return prev.slice(0, idx + 1)
+            }, 'back'),
+        [navigate],
+    )
+
+    const reset = useCallback(
+        (name) => navigate(() => [{ name: name || initialScreen, params: {} }]),
+        [navigate, initialScreen],
+    )
+
+    const canGoBack = stack.length > 1
+
+    const navigation = useMemo(
+        () => ({ push, pop, popTo, reset, canGoBack, stack }),
+        [push, pop, popTo, reset, canGoBack, stack],
+    )
+
+    const current = stack[stack.length - 1]
+    const def = screens[current.name]
+    if (!def) return null
+
+    const opt = (key, fallback) => (key in screenOptions ? screenOptions[key] : (def[key] ?? fallback))
+    const Component = def.component
+
+    const handleSetOptions = useCallback(
+        (opts) => {
+            const top = stackRef.current[stackRef.current.length - 1]
+            if (top.name === current.name) setScreenOptions((prev) => ({ ...prev, ...opts }))
+        },
+        [current.name],
+    )
+
+    const screenCtx = useMemo(
+        () => ({ name: current.name, params: current.params || {}, setOptions: handleSetOptions }),
+        [current.name, current.params, handleSetOptions],
+    )
+
+    return (
+        <NavigationContext.Provider value={navigation}>
+            <div style={{ display: 'flex', flexDirection: 'column', flex: 1, minHeight: 0 }}>
+                <Header
+                    title={opt('title')}
+                    onBack={canGoBack ? pop : undefined}
+                    headerLeft={opt('headerLeft')}
+                    headerRight={opt('headerRight')}
+                    allowClose={opt('allowClose', true)}
+                    onClose={opt('onClose')}
+                />
+                <div
+                    ref={wrapperRef}
+                    style={{ display: 'flex', flexDirection: 'column', flex: 1, minHeight: 0, overflow: 'hidden' }}
+                >
+                    <ScreenContext.Provider value={screenCtx} key={gen}>
+                        <Component />
+                    </ScreenContext.Provider>
+                </div>
+            </div>
+        </NavigationContext.Provider>
+    )
+}
+
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+
+/**
+ * Root layout component for extension panels.
+ * Provides the `moises` API via context and renders a full-height flex column.
+ *
+ * When `initialScreen` is provided, enters navigator mode: scans children for
+ * `<Extension.Screen>` elements and manages a navigation stack automatically.
+ * Otherwise, passes children through as-is (simple mode).
+ *
+ * @param {object} props
+ * @param {object} props.moises - The moises extension API instance.
+ * @param {string} [props.initialScreen] - Activates navigator mode with this screen.
+ * @param {boolean} [props.animated] - Enable slide+fade transitions (navigator mode only).
+ * @param {React.ReactNode} props.children - Extension sub-components or Screen elements.
+ */
+function Extension({ moises, initialScreen, animated, children }) {
+    return (
+        <ExtensionContext.Provider value={moises}>
+            <Flex direction="column" style={{ height: '100%' }}>
+                {initialScreen ? (
+                    <Navigator initialScreen={initialScreen} animated={animated}>
+                        {children}
+                    </Navigator>
+                ) : children}
+            </Flex>
+        </ExtensionContext.Provider>
+    )
+}
+
+Extension.Header = Header
+Extension.Content = Content
+Extension.Footer = Footer
+Extension.Screen = Screen
+
+export { Extension }

package/src/components/Extension/Extension.stories.jsx

@@ -0,0 +1,368 @@
+import { useEffect, useState } from 'react'
+import { Badge, Button, Card, Flex, IconButton, Text } from '../../index'
+import { DotsVerticalIcon } from '../../icons'
+import { Extension, useNavigation, useScreen } from './Extension'
+
+const mockMoises = {
+  extension: { close: () => console.log('extension.close()') },
+}
+
+const sidebarDecorator = (Story) => (
+  <div
+    style={{
+      width: 300,
+      height: 500,
+      border: '1px solid var(--gray-a6)',
+      borderRadius: 8,
+      overflow: 'hidden',
+      display: 'flex',
+      flexDirection: 'column',
+    }}
+  >
+    <Story />
+  </div>
+)
+
+export default {
+  title: 'Extensions/Extension',
+  decorators: [sidebarDecorator],
+  parameters: { layout: 'centered' },
+}
+
+// ---------------------------------------------------------------------------
+// Simple mode (flat layout, no navigation)
+// ---------------------------------------------------------------------------
+
+export const Simple = {
+  name: 'Simple (Header + Content + Footer)',
+  render: () => (
+    <Extension moises={mockMoises}>
+      <Extension.Header title="My Extension">
+        <Button variant="ghost" size="1">Action</Button>
+      </Extension.Header>
+      <Extension.Content>
+        <Card>Card content 1</Card>
+        <Card>Card content 2</Card>
+        <Card>Card content 3</Card>
+      </Extension.Content>
+      <Extension.Footer>
+        <Button variant="ghost" size="1">Footer Action</Button>
+      </Extension.Footer>
+    </Extension>
+  ),
+}
+
+export const HeaderOnly = {
+  name: 'Header Only',
+  render: () => (
+    <Extension moises={mockMoises}>
+      <Extension.Header title="Minimal" />
+      <Extension.Content>
+        <Text size="2">Content with a simple header above.</Text>
+      </Extension.Content>
+    </Extension>
+  ),
+}
+
+export const HeaderWithBackButton = {
+  name: 'Header with Back Button',
+  render: () => (
+    <Extension moises={mockMoises}>
+      <Extension.Header title="Detail View" onBack={() => console.log('onBack')} />
+      <Extension.Content>
+        <Text size="2">Passing `onBack` renders a back arrow on the left.</Text>
+      </Extension.Content>
+    </Extension>
+  ),
+}
+
+export const HeaderCustomLeft = {
+  name: 'Header with Custom Left',
+  render: () => (
+    <Extension moises={mockMoises}>
+      <Extension.Header
+        title="Custom Left"
+        headerLeft={<Badge variant="soft" size="1">v2</Badge>}
+      />
+      <Extension.Content>
+        <Text size="2">`headerLeft` replaces the default back button.</Text>
+      </Extension.Content>
+    </Extension>
+  ),
+}
+
+export const HeaderCustomRight = {
+  name: 'Header with Custom Right',
+  render: () => (
+    <Extension moises={mockMoises}>
+      <Extension.Header
+        title="Options"
+        headerRight={
+          <IconButton variant="ghost" color="gray" size="1">
+            <DotsVerticalIcon width={16} />
+          </IconButton>
+        }
+      />
+      <Extension.Content>
+        <Text size="2">`headerRight` adds actions before the close button.</Text>
+      </Extension.Content>
+    </Extension>
+  ),
+}
+
+export const HeaderNoClose = {
+  name: 'Header without Close Button',
+  render: () => (
+    <Extension moises={mockMoises}>
+      <Extension.Header title="No Close" allowClose={false} />
+      <Extension.Content>
+        <Text size="2">Close button hidden via `allowClose={'{false}'}`.</Text>
+      </Extension.Content>
+    </Extension>
+  ),
+}
+
+export const ScrollableContent = {
+  name: 'Scrollable Content',
+  render: () => (
+    <Extension moises={mockMoises}>
+      <Extension.Header title="Scrollable" />
+      <Extension.Content>
+        {Array.from({ length: 20 }, (_, i) => (
+          <Card key={i}>Item {i + 1}</Card>
+        ))}
+      </Extension.Content>
+      <Extension.Footer>
+        <Text size="1" color="gray">Footer stays pinned</Text>
+      </Extension.Footer>
+    </Extension>
+  ),
+}
+
+// ---------------------------------------------------------------------------
+// Navigator mode (screen stack with push/pop)
+// ---------------------------------------------------------------------------
+
+const ITEMS = [
+  { id: 'drums', name: 'Drums', desc: 'Acoustic drum kit with multiple mic positions' },
+  { id: 'bass', name: 'Bass', desc: 'Electric bass recorded through DI and amp' },
+  { id: 'guitar', name: 'Guitar', desc: 'Clean electric guitar with stereo chorus' },
+  { id: 'vocals', name: 'Vocals', desc: 'Lead vocals with studio compression' },
+  { id: 'keys', name: 'Keys', desc: 'Rhodes piano through a rotary speaker sim' },
+]
+
+function HomeScreen() {
+  const { push } = useNavigation()
+
+  return (
+    <>
+      <Extension.Content>
+        {ITEMS.map((item) => (
+          <Card
+            key={item.id}
+            style={{ cursor: 'pointer' }}
+            onClick={() => push('detail', { itemId: item.id, itemName: item.name })}
+          >
+            <Flex direction="column" gap="1">
+              <Text size="2" weight="medium">{item.name}</Text>
+              <Text size="1" color="gray">{item.desc}</Text>
+            </Flex>
+          </Card>
+        ))}
+      </Extension.Content>
+      <Extension.Footer>
+        <Button variant="ghost" size="1" onClick={() => push('settings')}>
+          View Stack
+        </Button>
+      </Extension.Footer>
+    </>
+  )
+}
+
+function DetailScreen() {
+  const { push } = useNavigation()
+  const { params, setOptions } = useScreen()
+  const item = ITEMS.find((i) => i.id === params.itemId)
+
+  useEffect(() => {
+    setOptions({ title: params.itemName })
+  }, [params.itemName])
+
+  if (!item) {
+    return (
+      <Extension.Content>
+        <Text size="2" color="gray">Item not found.</Text>
+      </Extension.Content>
+    )
+  }
+
+  return (
+    <Extension.Content>
+      <Flex direction="column" gap="2">
+        <Text size="2" weight="medium">{item.name}</Text>
+        <Text size="2" color="gray">{item.desc}</Text>
+      </Flex>
+      <Button variant="soft" size="2" onClick={() => push('editor', { itemId: item.id })}>
+        Open Editor
+      </Button>
+    </Extension.Content>
+  )
+}
+
+function EditorScreen() {
+  const { setOptions } = useScreen()
+  const [dirty, setDirty] = useState(false)
+
+  useEffect(() => {
+    setOptions({
+      headerRight: dirty ? (
+        <Button variant="soft" size="1" onClick={() => setDirty(false)}>Save</Button>
+      ) : null,
+    })
+  }, [dirty])
+
+  return (
+    <Extension.Content>
+      <Text size="2" color="gray">
+        {dirty ? 'You have unsaved changes.' : 'No changes yet.'}
+      </Text>
+      {!dirty && (
+        <Button variant="soft" size="2" onClick={() => setDirty(true)}>
+          Make a change
+        </Button>
+      )}
+    </Extension.Content>
+  )
+}
+
+function SettingsScreen() {
+  const { stack } = useNavigation()
+
+  return (
+    <Extension.Content>
+      <Text size="2" weight="medium">Navigation Stack</Text>
+      <Flex direction="column" gap="1">
+        {stack.map((entry, i) => (
+          <Flex key={i} align="center" gap="2">
+            <Badge variant="soft" size="1">{i}</Badge>
+            <Text size="1">{entry.name}</Text>
+          </Flex>
+        ))}
+      </Flex>
+    </Extension.Content>
+  )
+}
+
+export const NavigatorFull = {
+  name: 'Navigator (Multi-Screen)',
+  render: () => (
+    <Extension moises={mockMoises} initialScreen="home" animated>
+      <Extension.Screen name="home" title="Navigator Demo" component={HomeScreen}
+        headerRight={
+          <IconButton variant="ghost" color="gray" size="1">
+            <DotsVerticalIcon width={16} />
+          </IconButton>
+        }
+      />
+      <Extension.Screen name="detail" title="Detail" component={DetailScreen} />
+      <Extension.Screen name="editor" title="Editor" component={EditorScreen} />
+      <Extension.Screen name="settings" title="Settings" component={SettingsScreen} />
+    </Extension>
+  ),
+}
+
+// ---------------------------------------------------------------------------
+// Navigator — minimal two-screen example
+// ---------------------------------------------------------------------------
+
+function ListScreen() {
+  const { push } = useNavigation()
+
+  return (
+    <Extension.Content>
+      <Text size="2" color="gray">A minimal two-screen navigator.</Text>
+      <Button variant="soft" size="2" onClick={() => push('about')}>
+        Go to About
+      </Button>
+    </Extension.Content>
+  )
+}
+
+function AboutScreen() {
+  return (
+    <Extension.Content>
+      <Text size="2">This is the about screen. Press the back arrow to return.</Text>
+    </Extension.Content>
+  )
+}
+
+export const NavigatorMinimal = {
+  name: 'Navigator (Minimal)',
+  render: () => (
+    <Extension moises={mockMoises} initialScreen="list" animated>
+      <Extension.Screen name="list" title="Home" component={ListScreen} />
+      <Extension.Screen name="about" title="About" component={AboutScreen} />
+    </Extension>
+  ),
+}
+
+// ---------------------------------------------------------------------------
+// Navigator — dynamic header via setOptions
+// ---------------------------------------------------------------------------
+
+function CounterScreen() {
+  const { setOptions } = useScreen()
+  const [count, setCount] = useState(0)
+
+  useEffect(() => {
+    setOptions({
+      title: `Count: ${count}`,
+      headerRight: (
+        <Button variant="soft" size="1" onClick={() => setCount(0)}>Reset</Button>
+      ),
+    })
+  }, [count])
+
+  return (
+    <Extension.Content>
+      <Button variant="soft" size="2" onClick={() => setCount((c) => c + 1)}>
+        Increment
+      </Button>
+    </Extension.Content>
+  )
+}
+
+export const DynamicHeader = {
+  name: 'Navigator (Dynamic Header)',
+  render: () => (
+    <Extension moises={mockMoises} initialScreen="counter">
+      <Extension.Screen name="counter" title="Count: 0" component={CounterScreen} />
+    </Extension>
+  ),
+}
+
+// ---------------------------------------------------------------------------
+// Navigator — custom close handler
+// ---------------------------------------------------------------------------
+
+function CloseInfoScreen() {
+  return (
+    <Extension.Content>
+      <Text size="2">The close button on this screen triggers a custom handler instead of `moises.extension.close()`.</Text>
+    </Extension.Content>
+  )
+}
+
+export const CustomClose = {
+  name: 'Navigator (Custom Close)',
+  render: () => (
+    <Extension moises={mockMoises} initialScreen="info">
+      <Extension.Screen
+        name="info"
+        title="Custom Close"
+        component={CloseInfoScreen}
+        onClose={() => console.log('custom onClose handler')}
+      />
+    </Extension>
+  ),
+}