@open-mercato/core 0.6.7-develop.6788.1.c2a1520a30 → 0.6.7-develop.6795.1.8a3f27921c

package/src/modules/design_system/gallery/components/CodeSnippet.tsx

@@ -0,0 +1,55 @@
+'use client'
+
+import * as React from 'react'
+import { Copy } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { IconButton } from '@open-mercato/ui/primitives/icon-button'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+
+export function CodeSnippet({ code }: { code: string }) {
+  const t = useT()
+  const copyLabel = t('design_system.gallery.copy', 'Copy code')
+
+  const onCopy = React.useCallback(async () => {
+    try {
+      if (navigator.clipboard) {
+        await navigator.clipboard.writeText(code)
+      } else {
+        // Non-secure contexts (plain-HTTP self-hosted installs) have no
+        // navigator.clipboard — fall back to the legacy selection API.
+        const holder = document.createElement('textarea')
+        holder.value = code
+        holder.setAttribute('readonly', '')
+        holder.style.position = 'fixed'
+        holder.style.opacity = '0'
+        document.body.appendChild(holder)
+        holder.select()
+        const copied = document.execCommand('copy')
+        holder.remove()
+        if (!copied) throw new Error('[internal] execCommand copy failed')
+      }
+      flash(t('design_system.gallery.copied', 'Snippet copied to clipboard'), 'success')
+    } catch {
+      flash(t('design_system.gallery.copyFailed', 'Could not copy the snippet'), 'error')
+    }
+  }, [code, t])
+
+  return (
+    <div className="relative rounded-md border border-border bg-muted/50">
+      <pre className="overflow-x-auto p-3 pr-12 text-xs leading-relaxed">
+        <code>{code}</code>
+      </pre>
+      <IconButton
+        type="button"
+        variant="ghost"
+        size="sm"
+        className="absolute right-1.5 top-1.5"
+        aria-label={copyLabel}
+        title={copyLabel}
+        onClick={onCopy}
+      >
+        <Copy />
+      </IconButton>
+    </div>
+  )
+}

package/src/modules/design_system/gallery/components/EntryCard.tsx

@@ -0,0 +1,95 @@
+'use client'
+
+import * as React from 'react'
+import { Check, ExternalLink, X } from 'lucide-react'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { LinkButton } from '@open-mercato/ui/primitives/link-button'
+import type { GalleryEntry } from '../types'
+import { DS_DOCS_URL, figmaNodeUrl } from '../registry'
+import { VariantPreview } from './VariantPreview'
+import { CodeSnippet } from './CodeSnippet'
+
+export function EntryCard({ entry }: { entry: GalleryEntry }) {
+  const t = useT()
+
+  return (
+    <section
+      id={`gallery-entry-${entry.id}`}
+      aria-labelledby={`gallery-entry-${entry.id}-title`}
+      className="scroll-mt-4 space-y-4 rounded-lg border border-border bg-card p-4"
+    >
+      <div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
+        <div className="min-w-0 space-y-1">
+          <h3 id={`gallery-entry-${entry.id}-title`} className="text-base font-semibold leading-tight">
+            {entry.title}
+          </h3>
+          {entry.descriptionKey ? (
+            <p className="text-sm text-muted-foreground">{t(entry.descriptionKey, entry.title)}</p>
+          ) : null}
+          <code className="block truncate text-xs text-muted-foreground">{entry.importPath}</code>
+        </div>
+        <div className="flex shrink-0 items-center gap-3">
+          {entry.figmaNodeId ? (
+            <LinkButton asChild size="sm">
+              <a href={figmaNodeUrl(entry.figmaNodeId)} target="_blank" rel="noreferrer">
+                {t('design_system.gallery.openInFigma', 'Open in Figma')}
+                <ExternalLink />
+              </a>
+            </LinkButton>
+          ) : null}
+          {entry.docsAnchor ? (
+            <LinkButton asChild size="sm" variant="gray">
+              <a href={`${DS_DOCS_URL}${entry.docsAnchor}`} target="_blank" rel="noreferrer">
+                {t('design_system.gallery.viewDocs', 'View docs')}
+                <ExternalLink />
+              </a>
+            </LinkButton>
+          ) : null}
+        </div>
+      </div>
+      {entry.usage && (entry.usage.do?.length || entry.usage.dont?.length) ? (
+        <div className="grid gap-4 rounded-md border border-border bg-muted/30 p-4 sm:grid-cols-2">
+          {entry.usage.do?.length ? (
+            <div className="space-y-1.5">
+              <div className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+                {t('design_system.gallery.usageDo', 'Do')}
+              </div>
+              <ul className="space-y-1.5">
+                {entry.usage.do.map((rule) => (
+                  <li key={rule} className="flex items-start gap-2 text-sm text-foreground">
+                    <Check aria-hidden className="mt-0.5 size-3.5 shrink-0 text-status-success-icon" />
+                    <span>{rule}</span>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ) : null}
+          {entry.usage.dont?.length ? (
+            <div className="space-y-1.5">
+              <div className="text-xs font-medium uppercase tracking-wider text-muted-foreground">
+                {t('design_system.gallery.usageDont', "Don't")}
+              </div>
+              <ul className="space-y-1.5">
+                {entry.usage.dont.map((rule) => (
+                  <li key={rule} className="flex items-start gap-2 text-sm text-foreground">
+                    <X aria-hidden className="mt-0.5 size-3.5 shrink-0 text-status-error-icon" />
+                    <span>{rule}</span>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+      <div className="space-y-4">
+        {entry.variants.map((variant) => (
+          <div key={variant.id} className="space-y-2">
+            <div className="text-sm font-medium text-foreground">{variant.title}</div>
+            <VariantPreview>{variant.render()}</VariantPreview>
+            <CodeSnippet code={variant.code} />
+          </div>
+        ))}
+      </div>
+    </section>
+  )
+}

package/src/modules/design_system/gallery/components/GalleryShell.tsx

@@ -0,0 +1,206 @@
+'use client'
+
+import * as React from 'react'
+import { useSearchParams } from 'next/navigation'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { SectionPage } from '@open-mercato/ui/backend/section-page'
+import type { SectionNavGroup } from '@open-mercato/ui/backend/section-page'
+import { SearchInput } from '@open-mercato/ui/primitives/search-input'
+import { Skeleton } from '@open-mercato/ui/primitives/skeleton'
+import { EmptyState } from '@open-mercato/ui/primitives/empty-state'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { ErrorMessage } from '@open-mercato/ui/backend/detail'
+import type { GalleryEntry, GalleryFamily } from '../types'
+import { GALLERY_BASE_PATH, galleryFamilies } from '../registry'
+import { EntryCard } from './EntryCard'
+
+/** 'buttons' → 'Buttons' — untranslated fallback when a family labelKey has no message. */
+function familyLabelFallback(id: string): string {
+  return id.charAt(0).toUpperCase() + id.slice(1).replace(/[-_]/g, ' ')
+}
+
+function matchesQuery(entry: GalleryEntry, query: string): boolean {
+  const needle = query.trim().toLowerCase()
+  if (!needle) return true
+  if (entry.id.toLowerCase().includes(needle) || entry.title.toLowerCase().includes(needle)) return true
+  if (entry.keywords?.some((keyword) => keyword.toLowerCase().includes(needle))) return true
+  // 'radiobutton' should still find 'radio' — match when the query CONTAINS the id/title too.
+  return needle.includes(entry.id.toLowerCase()) || needle.includes(entry.title.toLowerCase())
+}
+
+type LoadedEntries = Record<string, GalleryEntry[]>
+
+export function GalleryShell() {
+  const t = useT()
+  const searchParams = useSearchParams()
+  const [loaded, setLoaded] = React.useState<LoadedEntries>({})
+  const [failed, setFailed] = React.useState<Record<string, boolean>>({})
+  const [search, setSearch] = React.useState('')
+  const pendingRef = React.useRef(new Set<string>())
+
+  const familyParam = searchParams?.get('family') ?? null
+  const entryParam = searchParams?.get('entry') ?? null
+
+  // Clicking a family in the section nav exits search mode — otherwise the
+  // query keeps precedence and family navigation appears dead.
+  React.useEffect(() => {
+    setSearch('')
+  }, [familyParam])
+  const activeFamily: GalleryFamily | undefined =
+    galleryFamilies.find((family) => family.id === familyParam) ?? galleryFamilies[0]
+  const activeFamilyId = activeFamily?.id ?? null
+
+  const loadFamily = React.useCallback((family: GalleryFamily) => {
+    if (pendingRef.current.has(family.id)) return
+    pendingRef.current.add(family.id)
+    setFailed((prev) => (prev[family.id] ? { ...prev, [family.id]: false } : prev))
+    family
+      .load()
+      .then((mod) => {
+        setLoaded((prev) => (prev[family.id] ? prev : { ...prev, [family.id]: mod.entries }))
+      })
+      .catch(() => {
+        pendingRef.current.delete(family.id)
+        setFailed((prev) => ({ ...prev, [family.id]: true }))
+      })
+  }, [])
+
+  // Lazy-load the active family; when searching, load every family so results
+  // span the whole gallery.
+  const searching = search.trim().length > 0
+  React.useEffect(() => {
+    if (searching) {
+      for (const family of galleryFamilies) loadFamily(family)
+    } else if (activeFamily) {
+      loadFamily(activeFamily)
+    }
+  }, [searching, activeFamily, loadFamily])
+
+  // Deep link: ?entry=<id> scrolls the entry into view once its family loaded.
+  const activeEntries = activeFamilyId ? loaded[activeFamilyId] : undefined
+  React.useEffect(() => {
+    if (!entryParam || searching || !activeEntries) return
+    const node = document.getElementById(`gallery-entry-${entryParam}`)
+    node?.scrollIntoView({ block: 'start' })
+  }, [entryParam, searching, activeEntries])
+
+  const sections: SectionNavGroup[] = React.useMemo(
+    () => [
+      {
+        id: 'families',
+        label: 'Families',
+        labelKey: 'design_system.gallery.familiesGroup',
+        items: galleryFamilies.map((family) => ({
+          id: family.id,
+          label: familyLabelFallback(family.id),
+          labelKey: family.labelKey,
+          icon: family.icon,
+          href: `${GALLERY_BASE_PATH}?family=${family.id}`,
+        })),
+      },
+    ],
+    [],
+  )
+
+  const renderFamilySkeleton = () => (
+    <div className="space-y-4" data-testid="gallery-family-skeleton">
+      <Skeleton className="h-40 w-full" />
+      <Skeleton className="h-40 w-full" />
+    </div>
+  )
+
+  const renderSearchResults = () => {
+    const groups = galleryFamilies
+      .map((family) => ({
+        family,
+        entries: (loaded[family.id] ?? []).filter((entry) => matchesQuery(entry, search)),
+      }))
+      .filter((group) => group.entries.length > 0)
+    const stillLoading = galleryFamilies.some((family) => !loaded[family.id] && !failed[family.id])
+    if (groups.length === 0 && stillLoading) return renderFamilySkeleton()
+    if (groups.length === 0) {
+      return (
+        <EmptyState
+          title={t('design_system.gallery.noResults', 'No components match your search')}
+        />
+      )
+    }
+    return (
+      <div className="space-y-8">
+        {groups.map(({ family, entries }) => (
+          <div key={family.id} className="space-y-4">
+            <h2 className="text-sm font-medium uppercase tracking-wider text-muted-foreground">
+              {t(family.labelKey, familyLabelFallback(family.id))}
+            </h2>
+            {entries.map((entry) => (
+              <EntryCard key={entry.id} entry={entry} />
+            ))}
+          </div>
+        ))}
+      </div>
+    )
+  }
+
+  const renderActiveFamily = () => {
+    if (!activeFamily) return null
+    const entries = loaded[activeFamily.id]
+    if (!entries && failed[activeFamily.id]) {
+      return (
+        <ErrorMessage
+          label={t('design_system.gallery.loadFailed', 'Could not load this family')}
+          action={
+            <Button type="button" variant="outline" size="sm" onClick={() => loadFamily(activeFamily)}>
+              {t('design_system.gallery.retry', 'Retry')}
+            </Button>
+          }
+        />
+      )
+    }
+    if (!entries) return renderFamilySkeleton()
+    return (
+      <div className="space-y-4">
+        <h2 className="text-lg font-semibold">
+          {t(activeFamily.labelKey, familyLabelFallback(activeFamily.id))}
+        </h2>
+        {entries.length > 1 ? (
+          <nav
+            aria-label={t('design_system.gallery.familyContents', 'Components in this family')}
+            className="flex flex-wrap items-center gap-1.5 rounded-md border border-border bg-muted/30 p-2"
+          >
+            {entries.map((entry) => (
+              <a
+                key={entry.id}
+                href={`#gallery-entry-${entry.id}`}
+                className="rounded-md border border-border bg-background px-2 py-1 text-xs text-foreground transition-colors hover:bg-muted focus-visible:outline-none focus-visible:shadow-focus"
+              >
+                {entry.title}
+              </a>
+            ))}
+          </nav>
+        ) : null}
+        {entries.map((entry) => (
+          <EntryCard key={entry.id} entry={entry} />
+        ))}
+      </div>
+    )
+  }
+
+  return (
+    <SectionPage
+      title="Design system"
+      titleKey="design_system.nav.title"
+      sections={sections}
+      activePath={activeFamilyId ? `${GALLERY_BASE_PATH}?family=${activeFamilyId}` : GALLERY_BASE_PATH}
+    >
+      <div className="mx-auto w-full max-w-5xl space-y-6">
+        <SearchInput
+          value={search}
+          onChange={setSearch}
+          placeholder={t('design_system.gallery.searchPlaceholder', 'Search components…')}
+          aria-label={t('design_system.gallery.searchPlaceholder', 'Search components…')}
+        />
+        {searching ? renderSearchResults() : renderActiveFamily()}
+      </div>
+    </SectionPage>
+  )
+}

package/src/modules/design_system/gallery/components/VariantPreview.tsx

@@ -0,0 +1,15 @@
+'use client'
+
+import * as React from 'react'
+
+/**
+ * Bordered stage a variant renders inside. Chrome uses semantic tokens only —
+ * the stage must never impose colors of its own on the previewed component.
+ */
+export function VariantPreview({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="flex flex-wrap items-center gap-3 rounded-md border border-border bg-background p-4">
+      {children}
+    </div>
+  )
+}

package/src/modules/design_system/gallery/entries/banners.tsx

@@ -0,0 +1,226 @@
+import * as React from 'react'
+import { CircleCheck, Rocket, Sparkles } from 'lucide-react'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { NextStepCallout } from '@open-mercato/ui/backend/NextStepCallout'
+import { ContextHelp } from '@open-mercato/ui/backend/ContextHelp'
+import type { GalleryEntry } from '../types'
+
+// Component titles and variant names are proper nouns from the codebase and
+// are deliberately not translated. `code` MUST contain the entry's importPath
+// (enforced by the registry-integrity test) and is always reviewed alongside
+// its sibling `render`.
+
+// `FlashMessages` itself is a singleton mounted by AppShell — the gallery only
+// demonstrates the imperative `flash()` API; the triggered toast renders
+// through the already-mounted singleton.
+const flashMessagesEntry: GalleryEntry = {
+  id: 'flash-messages',
+  title: 'FlashMessages',
+  importPath: '@open-mercato/ui/backend/FlashMessages',
+  variants: [
+    {
+      id: 'kinds',
+      title: 'flash() kinds (toast via the AppShell singleton)',
+      render: () => (
+        <>
+          <Button variant="outline" onClick={() => flash('Changes saved', 'success')}>
+            Fire success
+          </Button>
+          <Button variant="outline" onClick={() => flash('Sync scheduled', 'info')}>
+            Fire info
+          </Button>
+          <Button variant="outline" onClick={() => flash('Quota almost reached', 'warning')}>
+            Fire warning
+          </Button>
+          <Button variant="outline" onClick={() => flash('Save failed', 'error')}>
+            Fire error
+          </Button>
+        </>
+      ),
+      code: `import { flash } from '@open-mercato/ui/backend/FlashMessages'
+
+// FlashMessages is mounted once by AppShell — never mount your own.
+flash('Changes saved', 'success')
+flash('Sync scheduled', 'info')
+flash('Quota almost reached', 'warning')
+flash('Save failed', 'error')`,
+    },
+  ],
+}
+
+const nextStepCalloutEntry: GalleryEntry = {
+  id: 'next-step-callout',
+  title: 'NextStepCallout',
+  importPath: '@open-mercato/ui/backend/NextStepCallout',
+  variants: [
+    {
+      id: 'basic',
+      title: 'Basic',
+      render: () => (
+        <div className="w-full">
+          <NextStepCallout
+            icon={<Rocket className="size-6" />}
+            title="Publish your catalog"
+            description="Products are imported and priced. Publishing makes them visible on every sales channel."
+            actionLabel="Publish catalog"
+            actionIcon={<Sparkles className="mr-2 size-4" />}
+            onAction={() => {}}
+          />
+        </div>
+      ),
+      code: `import { Rocket, Sparkles } from 'lucide-react'
+import { NextStepCallout } from '@open-mercato/ui/backend/NextStepCallout'
+
+<NextStepCallout
+  icon={<Rocket className="size-6" />}
+  title="Publish your catalog"
+  description="Products are imported and priced. Publishing makes them visible on every sales channel."
+  actionLabel="Publish catalog"
+  actionIcon={<Sparkles className="mr-2 size-4" />}
+  onAction={handlePublish}
+/>`,
+    },
+    {
+      id: 'with-steps',
+      title: 'With steps',
+      render: () => (
+        <div className="w-full">
+          <NextStepCallout
+            title="Finish store setup"
+            description="Two steps are done — connect a payment provider to start selling."
+            steps={[
+              { id: 'import', label: 'Import products', state: 'completed' },
+              { id: 'pricing', label: 'Set pricing', state: 'completed' },
+              { id: 'payments', label: 'Connect payments', state: 'active' },
+              { id: 'launch', label: 'Launch', state: 'pending' },
+            ]}
+            actionLabel="Connect payments"
+            onAction={() => {}}
+          />
+        </div>
+      ),
+      code: `import { NextStepCallout } from '@open-mercato/ui/backend/NextStepCallout'
+
+<NextStepCallout
+  title="Finish store setup"
+  description="Two steps are done — connect a payment provider to start selling."
+  steps={[
+    { id: 'import', label: 'Import products', state: 'completed' },
+    { id: 'pricing', label: 'Set pricing', state: 'completed' },
+    { id: 'payments', label: 'Connect payments', state: 'active' },
+    { id: 'launch', label: 'Launch', state: 'pending' },
+  ]}
+  actionLabel="Connect payments"
+  onAction={handleConnect}
+/>`,
+    },
+    {
+      id: 'with-status',
+      title: 'With status progress',
+      render: () => (
+        <div className="w-full">
+          <NextStepCallout
+            title="Index your products"
+            description="Search stays disabled until the first indexing run completes."
+            actionLabel="Re-run indexing"
+            onAction={() => {}}
+            busy
+            status={{
+              tone: 'info',
+              icon: <CircleCheck className="size-4" />,
+              label: 'Indexing in progress',
+              progressValue: 64,
+              progressDescription: '1,280 of 2,000 products indexed',
+            }}
+          />
+        </div>
+      ),
+      code: `import { CircleCheck } from 'lucide-react'
+import { NextStepCallout } from '@open-mercato/ui/backend/NextStepCallout'
+
+<NextStepCallout
+  title="Index your products"
+  description="Search stays disabled until the first indexing run completes."
+  actionLabel="Re-run indexing"
+  onAction={handleReindex}
+  busy
+  status={{
+    tone: 'info',
+    icon: <CircleCheck className="size-4" />,
+    label: 'Indexing in progress',
+    progressValue: 64,
+    progressDescription: '1,280 of 2,000 products indexed',
+  }}
+/>`,
+    },
+  ],
+}
+
+const contextHelpEntry: GalleryEntry = {
+  id: 'context-help',
+  title: 'ContextHelp',
+  importPath: '@open-mercato/ui/backend/ContextHelp',
+  variants: [
+    {
+      id: 'default',
+      title: 'default (collapsed)',
+      render: () => (
+        <div className="w-full max-w-md">
+          <ContextHelp title="How do exchange rates work?">
+            Rates refresh nightly from the configured provider. Manual overrides
+            stay pinned until you clear them.
+          </ContextHelp>
+        </div>
+      ),
+      code: `import { ContextHelp } from '@open-mercato/ui/backend/ContextHelp'
+
+<ContextHelp title="How do exchange rates work?">
+  Rates refresh nightly from the configured provider. Manual overrides
+  stay pinned until you clear them.
+</ContextHelp>`,
+    },
+    {
+      id: 'default-open',
+      title: 'defaultOpen',
+      render: () => (
+        <div className="w-full max-w-md">
+          <ContextHelp title="Why is this field required?" defaultOpen>
+            The tax office identifier is mandatory for invoices issued to
+            companies registered in the EU.
+          </ContextHelp>
+        </div>
+      ),
+      code: `import { ContextHelp } from '@open-mercato/ui/backend/ContextHelp'
+
+<ContextHelp title="Why is this field required?" defaultOpen>
+  The tax office identifier is mandatory for invoices issued to
+  companies registered in the EU.
+</ContextHelp>`,
+    },
+    {
+      id: 'info-icon',
+      title: 'Info icon (bulb={false})',
+      render: () => (
+        <div className="w-full max-w-md">
+          <ContextHelp title="About draft orders" bulb={false} defaultOpen>
+            Draft orders are invisible to customers and skip stock reservation
+            until they are confirmed.
+          </ContextHelp>
+        </div>
+      ),
+      code: `import { ContextHelp } from '@open-mercato/ui/backend/ContextHelp'
+
+<ContextHelp title="About draft orders" bulb={false} defaultOpen>
+  Draft orders are invisible to customers and skip stock reservation
+  until they are confirmed.
+</ContextHelp>`,
+    },
+  ],
+}
+
+export const entries: GalleryEntry[] = [
+  flashMessagesEntry,
+  nextStepCalloutEntry,
+  contextHelpEntry,
+]