@almanaclabs/blaze-ui 0.4.0 → 0.5.0

package/recipes/guided-workflow/guided-workflow.tsx

@@ -0,0 +1,495 @@
+import type { ReactNode } from 'react'
+import {
+  IconAlertCircle,
+  IconCheck,
+  IconChevronRight,
+} from '@tabler/icons-react'
+
+import {
+  Badge,
+  Button,
+  NavigationAction,
+  Progress,
+  cn,
+} from '@almanaclabs/blaze-ui'
+
+export type GuidedWorkflowStep = {
+  key: string
+  label: string
+  description?: string
+}
+
+export type GuidedWorkflowItemStatus = 'complete' | 'attention' | 'pending'
+
+export type GuidedWorkflowItem = {
+  key: string
+  label: string
+  description?: string
+  status?: GuidedWorkflowItemStatus
+  statusLabel?: string
+}
+
+export type GuidedWorkflowVariant = 'default' | 'compact'
+
+export type GuidedWorkflowRecipeProps = {
+  title: string
+  steps: readonly GuidedWorkflowStep[]
+  activeStepKey: string
+  railLabel: string
+  items: readonly GuidedWorkflowItem[]
+  activeItemKey: string
+  onItemSelect: (key: string) => void
+  children: ReactNode
+  backLabel?: string
+  continueLabel?: string
+  continueDisabled?: boolean
+  footerStatus?: ReactNode
+  secondaryActions?: ReactNode
+  onBack?: () => void
+  onContinue: () => void
+  variant?: GuidedWorkflowVariant
+  className?: string
+}
+
+export type GuidedWorkflowPageHeaderProps = {
+  title: string
+  steps: readonly GuidedWorkflowStep[]
+  activeStepKey: string
+  variant?: GuidedWorkflowVariant
+  className?: string
+}
+
+export type GuidedWorkflowBodyProps = {
+  railLabel: string
+  items: readonly GuidedWorkflowItem[]
+  activeItemKey: string
+  onItemSelect: (key: string) => void
+  children: ReactNode
+  contentLabel?: string
+  variant?: GuidedWorkflowVariant
+  className?: string
+}
+
+export type GuidedWorkflowFooterProps = {
+  backLabel?: string
+  continueLabel?: string
+  continueDisabled?: boolean
+  footerStatus?: ReactNode
+  secondaryActions?: ReactNode
+  onBack?: () => void
+  onContinue: () => void
+  variant?: GuidedWorkflowVariant
+  className?: string
+}
+
+export type GuidedWorkflowSectionProps = {
+  title: ReactNode
+  icon?: ReactNode
+  description?: ReactNode
+  action?: ReactNode
+  children: ReactNode
+  className?: string
+  markerClassName?: string
+}
+
+const statusConfiguration = {
+  attention: {
+    fallbackLabel: 'Needs attention',
+    icon: IconAlertCircle,
+    variant: 'destructive',
+  },
+  complete: {
+    fallbackLabel: 'Complete',
+    icon: IconCheck,
+    variant: 'success',
+  },
+  pending: {
+    fallbackLabel: 'Pending',
+    icon: null,
+    variant: 'secondary',
+  },
+} as const
+
+function WorkflowItemStatus({ item }: { item: GuidedWorkflowItem }) {
+  if (!item.status) return null
+
+  const configuration = statusConfiguration[item.status]
+  const Icon = configuration.icon
+
+  return (
+    <Badge variant={configuration.variant}>
+      {Icon ? <Icon data-icon="inline-start" aria-hidden="true" /> : null}
+      {item.statusLabel ?? configuration.fallbackLabel}
+    </Badge>
+  )
+}
+
+export function GuidedWorkflowSections({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return <div className={cn('grid gap-8', className)} {...props} />
+}
+
+export function GuidedWorkflowSection({
+  title,
+  icon,
+  description,
+  action,
+  children,
+  className,
+  markerClassName,
+}: GuidedWorkflowSectionProps) {
+  return (
+    <section
+      className={cn(
+        'grid gap-5 border-b border-border pb-8 last:border-b-0 last:pb-0',
+        className,
+      )}
+    >
+      <header className="flex min-w-0 items-start justify-between gap-4">
+        <div className="flex min-w-0 items-center gap-2.5">
+          {icon ? (
+            <span
+              className={cn(
+                'grid size-8 shrink-0 place-items-center rounded-full text-primary-foreground [--icon-stroke-width:var(--icon-stroke-16)] [&>svg:not([class*=size-])]:size-4',
+                markerClassName,
+              )}
+              aria-hidden="true"
+            >
+              {icon}
+            </span>
+          ) : null}
+          <div className="min-w-0">
+            <h2 className="type-section-title font-normal text-foreground">
+              {title}
+            </h2>
+            {description ? (
+              <p className="type-body mt-1 text-muted-foreground">
+                {description}
+              </p>
+            ) : null}
+          </div>
+        </div>
+        {action}
+      </header>
+      <div className="min-w-0">{children}</div>
+    </section>
+  )
+}
+
+function getActiveStepIndex(
+  steps: readonly GuidedWorkflowStep[],
+  activeStepKey: string,
+) {
+  return Math.max(
+    0,
+    steps.findIndex((step) => step.key === activeStepKey),
+  )
+}
+
+export function GuidedWorkflowPageHeader({
+  title,
+  steps,
+  activeStepKey,
+  variant = 'default',
+  className,
+}: GuidedWorkflowPageHeaderProps) {
+  const activeStepIndex = getActiveStepIndex(steps, activeStepKey)
+  const activeStep = steps[activeStepIndex]
+  const progressValue =
+    steps.length === 0 ? 0 : ((activeStepIndex + 1) / steps.length) * 100
+
+  return (
+    <header
+      className={cn(
+        'border-b bg-background px-4 md:px-6',
+        variant === 'compact' ? 'flex min-h-[76px] items-center py-3' : 'py-4',
+        className,
+      )}
+    >
+      <div className="flex w-full flex-col gap-4 xl:flex-row xl:items-center xl:justify-between">
+        <div className="min-w-0">
+          {variant === 'default' ? (
+            <p className="type-meta text-muted-foreground uppercase">
+              Step {steps.length === 0 ? 0 : activeStepIndex + 1} of{' '}
+              {steps.length}
+            </p>
+          ) : null}
+          <h1
+            className={cn(
+              'type-page-title truncate font-normal',
+              variant === 'default' && 'mt-1',
+            )}
+          >
+            {title}
+          </h1>
+          {variant === 'default' && activeStep?.description ? (
+            <p className="mt-1 text-sm text-muted-foreground">
+              {activeStep.description}
+            </p>
+          ) : null}
+        </div>
+
+        <nav aria-label="Workflow progress" className="min-w-0 xl:w-3/5">
+          <ol className="type-meta flex min-w-max items-center gap-2 overflow-x-auto pb-1 sm:min-w-0 sm:justify-end">
+            {steps.map((step, index) => {
+              const complete = index < activeStepIndex
+              const active = index === activeStepIndex
+
+              return (
+                <li
+                  key={step.key}
+                  aria-current={active ? 'step' : undefined}
+                  className={cn(
+                    'flex items-center gap-2 text-muted-foreground',
+                    active && 'font-medium text-foreground',
+                  )}
+                >
+                  <span
+                    className={cn(
+                      'grid shrink-0 place-items-center border bg-muted',
+                      variant === 'compact'
+                        ? 'size-4 rounded-[4px] text-[0.625rem]'
+                        : 'size-5 rounded-md text-[0.65rem]',
+                      active && 'border-foreground/40 bg-background',
+                      complete &&
+                        variant === 'default' &&
+                        'border-primary bg-primary text-primary-foreground',
+                    )}
+                    aria-hidden="true"
+                  >
+                    {complete && variant === 'default' ? (
+                      <IconCheck className="size-3" />
+                    ) : (
+                      index + 1
+                    )}
+                  </span>
+                  <span>{step.label}</span>
+                  {index < steps.length - 1 ? (
+                    <IconChevronRight
+                      className="size-3.5 text-border"
+                      aria-hidden="true"
+                    />
+                  ) : null}
+                </li>
+              )
+            })}
+          </ol>
+          {variant === 'default' ? (
+            <Progress
+              value={progressValue}
+              aria-label={`${title} progress`}
+              className="mt-2 gap-0"
+            />
+          ) : null}
+        </nav>
+      </div>
+    </header>
+  )
+}
+
+export function GuidedWorkflowBody({
+  railLabel,
+  items,
+  activeItemKey,
+  onItemSelect,
+  children,
+  contentLabel,
+  variant = 'default',
+  className,
+}: GuidedWorkflowBodyProps) {
+  return (
+    <div
+      className={cn(
+        'grid min-h-0 grid-rows-[auto_minmax(0,1fr)]',
+        variant === 'compact'
+          ? 'md:grid-cols-[21.25rem_minmax(0,1fr)] md:grid-rows-1'
+          : 'lg:grid-cols-[20rem_minmax(0,1fr)] lg:grid-rows-1',
+        className,
+      )}
+    >
+      <aside
+        className={cn(
+          'min-w-0 border-b',
+          variant === 'compact'
+            ? 'bg-background md:border-r md:border-b-0'
+            : 'bg-surface-subtle lg:border-r lg:border-b-0',
+        )}
+      >
+        <nav
+          aria-label={railLabel}
+          className={cn(
+            'flex gap-2 overflow-x-auto p-3',
+            variant === 'compact'
+              ? 'md:grid md:max-h-full md:overflow-y-auto md:p-6'
+              : 'lg:grid lg:max-h-full lg:overflow-y-auto lg:p-5',
+          )}
+        >
+          <p
+            className={cn(
+              'type-label hidden px-2 font-medium text-foreground',
+              variant === 'compact' ? 'md:block' : 'lg:block',
+            )}
+          >
+            {railLabel}
+          </p>
+          {items.map((item) => {
+            const selected = item.key === activeItemKey
+
+            return (
+              <NavigationAction
+                key={item.key}
+                type="button"
+                aria-current={selected ? 'page' : undefined}
+                onClick={() => onItemSelect(item.key)}
+                className={cn(
+                  'h-auto min-w-64 items-start justify-start whitespace-normal border border-transparent px-3 py-3 text-left',
+                  variant === 'compact'
+                    ? 'md:min-w-0 md:w-full'
+                    : 'lg:min-w-0 lg:w-full',
+                  variant === 'compact' && 'rounded-sm md:min-h-19 md:px-5',
+                )}
+              >
+                <span className="grid min-w-0 flex-1 gap-1">
+                  <span className="type-content truncate font-normal">
+                    {item.label}
+                  </span>
+                  {item.description ? (
+                    <span className="type-body truncate font-normal text-muted-foreground">
+                      {item.description}
+                    </span>
+                  ) : null}
+                  <WorkflowItemStatus item={item} />
+                </span>
+              </NavigationAction>
+            )
+          })}
+        </nav>
+      </aside>
+
+      <section
+        aria-label={contentLabel ?? railLabel}
+        className={cn(
+          'min-w-0 overflow-y-auto',
+          variant === 'compact' ? 'bg-background' : 'bg-surface-subtle',
+        )}
+      >
+        <div
+          className={cn(
+            'mx-auto w-full p-4 md:p-8',
+            variant === 'compact' ? 'max-w-none md:p-6' : 'max-w-5xl lg:p-10',
+          )}
+        >
+          {children}
+        </div>
+      </section>
+    </div>
+  )
+}
+
+export function GuidedWorkflowFooter({
+  backLabel = 'Back',
+  continueLabel = 'Continue',
+  continueDisabled = false,
+  footerStatus,
+  secondaryActions,
+  onBack,
+  onContinue,
+  variant = 'default',
+  className,
+}: GuidedWorkflowFooterProps) {
+  return (
+    <footer
+      className={cn(
+        'flex flex-wrap items-center justify-between gap-3 border-t bg-background px-4 py-3 md:px-6',
+        variant === 'compact' ? 'min-h-[88px]' : 'min-h-16',
+        className,
+      )}
+    >
+      <div className="flex min-w-0 items-center gap-3">
+        {onBack ? (
+          <Button type="button" variant="secondary" size="md" onClick={onBack}>
+            {backLabel}
+          </Button>
+        ) : null}
+        {footerStatus ? (
+          <div className="truncate text-sm text-muted-foreground">
+            {footerStatus}
+          </div>
+        ) : null}
+      </div>
+      <div className="flex items-center gap-2">
+        {secondaryActions}
+        <Button
+          type="button"
+          size="md"
+          disabled={continueDisabled}
+          onClick={onContinue}
+        >
+          {continueLabel}
+          <IconChevronRight data-icon="inline-end" aria-hidden="true" />
+        </Button>
+      </div>
+    </footer>
+  )
+}
+
+export function GuidedWorkflowRecipe({
+  title,
+  steps,
+  activeStepKey,
+  railLabel,
+  items,
+  activeItemKey,
+  onItemSelect,
+  children,
+  backLabel = 'Back',
+  continueLabel = 'Continue',
+  continueDisabled = false,
+  footerStatus,
+  secondaryActions,
+  onBack,
+  onContinue,
+  variant = 'default',
+  className,
+}: GuidedWorkflowRecipeProps) {
+  const activeStepIndex = getActiveStepIndex(steps, activeStepKey)
+  const activeStep = steps[activeStepIndex]
+
+  return (
+    <section
+      className={cn(
+        'grid h-dvh min-h-[720px] grid-rows-[auto_minmax(0,1fr)_auto] overflow-hidden bg-background text-foreground',
+        className,
+      )}
+    >
+      <GuidedWorkflowPageHeader
+        title={title}
+        steps={steps}
+        activeStepKey={activeStepKey}
+        variant={variant}
+      />
+      <GuidedWorkflowBody
+        railLabel={railLabel}
+        items={items}
+        activeItemKey={activeItemKey}
+        onItemSelect={onItemSelect}
+        contentLabel={activeStep?.label ?? title}
+        variant={variant}
+      >
+        {children}
+      </GuidedWorkflowBody>
+      <GuidedWorkflowFooter
+        backLabel={backLabel}
+        continueLabel={continueLabel}
+        continueDisabled={continueDisabled}
+        footerStatus={footerStatus}
+        secondaryActions={secondaryActions}
+        onBack={onBack}
+        onContinue={onContinue}
+        variant={variant}
+      />
+    </section>
+  )
+}

package/recipes/manifest.json

@@ -3,10 +3,17 @@
   "recipes": [
     {
       "name": "workspace-shell",
-      "description": "Authenticated Blaze workspace chrome with access-mode theming, navigation, and an empty page-content slot.",
+      "description": "Authenticated Blaze workspace chrome with shared standard and focused modes, replaceable identity, page chrome, and pinned actions.",
       "dependencies": ["@almanaclabs/blaze-ui", "@tabler/icons-react"],
       "entry": "workspace-shell/workspace-shell.tsx",
       "instructions": "workspace-shell/README.md"
+    },
+    {
+      "name": "guided-workflow",
+      "description": "Multi-step creation and review flow with ordered progress, contextual work-item navigation, a focused canvas, and persistent actions.",
+      "dependencies": ["@almanaclabs/blaze-ui", "@tabler/icons-react"],
+      "entry": "guided-workflow/guided-workflow.tsx",
+      "instructions": "guided-workflow/README.md"
     }
   ]
 }

package/recipes/workspace-shell/README.md

@@ -1,41 +1,95 @@
 # Workspace shell recipe
 
-Use this recipe for authenticated pages that sit inside a selected customer
-workspace. It establishes the persistent application chrome; the page owns only the
-content rendered inside the shell.
+Use this recipe for authenticated Blaze pages inside a selected customer
+workspace. It establishes one persistent application frame; the page supplies its
+own navigation, workflow header, canvas, and actions through slots.
+
+## Modes
+
+- `standard`: dashboard, settings, reporting, and channel-management pages. The
+  content area owns its scrolling.
+- `focused`: creation and review flows. The content slot owns its internal rail and
+  canvas scrolling, while the optional shell footer stays pinned.
+
+Both modes preserve the same account sidebar, outer workspace gutter, rounded
+workspace frame, and 56px channel header. A focused workflow is content inside the
+workspace shell, not a second application shell.
 
 ## Preserve
 
-- One `SidebarProvider` wrapping the sidebar and inset.
-- Primary and settings navigation landmarks with an active item marked by
+- One `SidebarProvider` wrapping the 220px sidebar and workspace inset.
+- A 10px desktop gutter around the bordered, rounded workspace frame.
+- A 76px workspace-identity header aligning the identity to the channel title,
+  followed by the same 8px section inset in every shell mode.
+- `Manage` and `Channels` navigation groups with the active destination marked by
   `aria-current="page"`.
-- A single page heading in the sticky header.
-- Optional page-level navigation centered in the header on desktop and available in
-  the normal document order.
-- The sidebar's icon-collapse and mobile-sheet behavior.
-- Semantic Blaze UI colors and spacing.
-- Access-mode theming: AM mode always uses the light sidebar; client mode always uses
-  the dark sidebar.
+- 12px medium section labels and 14px regular destination text using the 90%
+  foreground in default, hover, and selected states.
+- 15px rail icons using the same 90% foreground as their destination labels in
+  default, hover, and selected states.
+- The bespoke Home glyph from the approved workspace-shell Figma frame, inlined
+  with `currentColor` and the system 7/6px rendered stroke at 15px; do not
+  substitute the Tabler Home icon.
+- Shared `NavigationAction` / `navigationActionVariants` styling for rail
+  destinations and standard shell tabs: transparent default, muted hover, and
+  8% selected surface.
+- Workspace and account menus composed as specialized tertiary `Button` triggers,
+  rather than one-off native-button states. Their surfaces share the navigation
+  row's 10px inset and pad from the identity icon so hover does not begin at the
+  glyph edge; both retain the default 32px control height for balanced vertical
+  space around the identity mark.
+- Rail collapse, expansion, and settings actions use tertiary `icon-sm` buttons
+  without overriding their system size or hit area.
+- The expanded rail uses `SidebarRail` resize mode with a 220px default, 200–320px
+  caps, a transparent edge at rest, a centered 2px divider on hover/focus/drag,
+  column-resize cursor, pointer dragging, and Arrow/Home/End keyboard control.
+  Width and caps remain configurable.
+- A 55px collapsed rail that preserves row and group geometry, hides visible
+  labels without removing their layout slots, stacks Settings above the profile,
+  and moves the expand control into the channel header. Collapse and expansion use
+  a 150ms Material standard curve with staged label fades for a settled endpoint.
+  Those pattern-specific rules live in `workspace-shell.css`, not the global
+  Blaze UI stylesheet.
+- An 8px first-section inset that combines with the identity header's bottom
+  padding to optically match the 24px separation between navigation groups; shell
+  mode must not alter left-rail geometry.
+- A single channel header with replaceable channel identity and action slots.
+- The shell's responsive mobile sheet and desktop icon-collapse behavior.
+- An optional page-header slot above the content and an optional 88px pinned action
+  footer below it.
+- Söhne typography, optical icon sizing, semantic colors, and shared Blaze UI
+  controls.
 
 ## Adapt
 
-- Replace the fictional workspace and user with serialized application data.
-- Declare `@tabler/icons-react` as an application dependency because the copied
-  recipe imports its navigation icons directly.
+- Replace the reference workspace, channel, and user identity through
+  `workspaceMark`, `channelMark`, and `userAvatar`.
+- Keep fixed brand marks resolution-independent where a vector source exists. When
+  a workspace avatar is raster-only, retain the original high-density source and
+  size it explicitly in the slot rather than generating a CSS-sized derivative.
+- Keep workspace and channel marks in a 24px identity container with 20px centered
+  artwork by composing `IdentityMark` and `IdentityMarkImage`. Compose account
+  avatars with `Avatar size="xs" shape="rounded"` for the 20px box and 6px corner
+  radius. Account labels use the same 14px regular weight as navigation
+  destinations.
 - Replace `href` values through the application's routing layer. In Inertia
   applications, render `Link` through the Blaze UI component's `render` prop rather
   than adding a parallel client-side router.
-- Derive the active item and access mode from server-authorized page data.
-- Fill the empty content area with the prototype's page-specific design. The shell
-  recipe deliberately provides no example page content.
+- Pass application-specific navigation groups and derive the active key from the
+  current route.
+- Put standard tabs and page titles in `pageHeader`.
+- Put guided-workflow progress in `pageHeader`, its rail and canvas in `children`,
+  and its actions in `footer` with `mode="focused"`.
+- Keep routing, authorization, persistence, and workflow state in the application.
 
 ## Avoid
 
-- Importing this recipe as a runtime package component.
-- Moving routing, authorization, access switching, or data fetching into the recipe.
-- Rebuilding the sidebar, header, or responsive behavior with arbitrary CSS.
-- Using production customer names, emails, logos, or metrics in Storybook.
+- Importing this recipe as a runtime package component; copy and adapt its source.
+- Creating separate outer shells for dashboard and creation-flow routes.
+- Placing page titles, tabs, or domain state inside the persistent sidebar.
+- Hiding workflow actions in the scrolling canvas when they must remain available.
+- Using production customer data in Storybook.
 
-Start from `workspace-shell.tsx`. Use the hosted Storybook
-`Recipes/Workspace shell` entry to review expanded, collapsed, AM-mode, client-mode,
-and mobile states.
+Start from `workspace-shell.tsx` and its colocated `workspace-shell.css`. Review
+`Recipes/Workspace shell/Standard` and `Recipes/Workspace shell/Focused Campaign`
+in Storybook before adapting them.

package/recipes/workspace-shell/assets/google-search-ads.svg

@@ -0,0 +1,6 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M16 8.18185C16 7.61458 15.9481 7.06913 15.8516 6.54549H8.16326V9.64003H12.5566C12.3673 10.64 11.7922 11.4873 10.9276 12.0546V14.0618H13.5659C15.1095 12.6691 16 10.6182 16 8.18185Z" fill="#4285F4"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M8.16327 16C10.3674 16 12.2152 15.2837 13.5659 14.0618L10.9276 12.0546C10.1967 12.5346 9.26161 12.8182 8.16327 12.8182C6.03711 12.8182 4.23748 11.4109 3.59555 9.51998H0.868279V11.5927C2.21151 14.2072 4.97218 16 8.16327 16Z" fill="#34A853"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M3.59555 9.51998C3.43229 9.03998 3.33952 8.5273 3.33952 8.00003C3.33952 7.47276 3.43228 6.96003 3.59555 6.48003V4.40731H0.868275C0.315399 5.48731 0 6.70912 0 8.00003C0 9.29094 0.315403 10.5127 0.868279 11.5927L3.59555 9.51998Z" fill="#FBBC05"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M8.16327 3.18181C9.36179 3.18181 10.4379 3.58545 11.2839 4.37818L13.6252 2.08363C12.2115 0.792726 10.3636 0 8.16327 0C4.97218 0 2.2115 1.79277 0.868275 4.40731L3.59555 6.48003C4.23748 4.58913 6.03711 3.18181 8.16327 3.18181Z" fill="#EA4335"/>
+</svg>

package/recipes/workspace-shell/assets/home.svg

@@ -0,0 +1,5 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="15" height="15" viewBox="0 0 15 15" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g id="icon">
+<path id="Icon" d="M4.6875 10.6641H10.3125M7.06536 2.00698L2.19036 5.30377C1.99251 5.43757 1.875 5.65416 1.875 5.88503V12.0551C1.875 12.646 2.37868 13.125 3 13.125H12C12.6213 13.125 13.125 12.646 13.125 12.0551V5.88503C13.125 5.65416 13.0075 5.43757 12.8096 5.30377L7.93464 2.00698C7.67442 1.83101 7.32558 1.83101 7.06536 2.00698Z" stroke="black" stroke-opacity="0.9" stroke-linecap="round" stroke-linejoin="round"/>
+</g>
+</svg>