@almanaclabs/blaze-ui 0.3.2 → 0.5.0

package/dist/lib/control-size.d.ts

@@ -0,0 +1,9 @@
+export declare const controlSizeClassNames: {
+    readonly xs: "h-6 rounded-[6px] px-1.5 text-[13px] leading-[14px] tracking-[0.01em] [--control-padding-inline:0.375rem]";
+    readonly sm: "h-7 rounded-[6px] px-2 text-sm leading-5 tracking-[0.01em] [--control-padding-inline:0.5rem]";
+    readonly md: "h-8 rounded-[8px] px-[11px] text-sm leading-[15px] tracking-[0.01em] [--control-padding-inline:11px]";
+    readonly lg: "h-9 rounded-[8px] px-[13px] text-base leading-[15px] [--control-padding-inline:13px]";
+    readonly xl: "h-12 rounded-[10px] px-[18px] text-base leading-5 [--control-padding-inline:18px]";
+};
+export type ControlSize = keyof typeof controlSizeClassNames;
+//# sourceMappingURL=control-size.d.ts.map

package/dist/lib/control-size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-size.d.ts","sourceRoot":"","sources":["../../src/lib/control-size.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB;;;;;;CAMxB,CAAA;AAEV,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,qBAAqB,CAAA"}

package/dist/lib/control-size.js

@@ -0,0 +1,10 @@
+//#region src/lib/control-size.ts
+var e = {
+	xs: "h-6 rounded-[6px] px-1.5 text-[13px] leading-[14px] tracking-[0.01em] [--control-padding-inline:0.375rem]",
+	sm: "h-7 rounded-[6px] px-2 text-sm leading-5 tracking-[0.01em] [--control-padding-inline:0.5rem]",
+	md: "h-8 rounded-[8px] px-[11px] text-sm leading-[15px] tracking-[0.01em] [--control-padding-inline:11px]",
+	lg: "h-9 rounded-[8px] px-[13px] text-base leading-[15px] [--control-padding-inline:13px]",
+	xl: "h-12 rounded-[10px] px-[18px] text-base leading-5 [--control-padding-inline:18px]"
+};
+//#endregion
+export { e as controlSizeClassNames };

package/dist/lib/utils.js

@@ -0,0 +1,8 @@
+import { clsx as e } from "clsx";
+import { twMerge as t } from "tailwind-merge";
+//#region src/lib/utils.ts
+function n(...n) {
+	return t(e(n));
+}
+//#endregion
+export { n as cn };

package/dist/recipes/recipe-runtime.d.ts

@@ -0,0 +1,18 @@
+export * from '../components/avatar';
+export * from '../components/badge';
+export * from '../components/button';
+export * from '../components/card';
+export * from '../components/dropdown-menu';
+export * from '../components/field';
+export * from '../components/input';
+export * from '../components/input-group';
+export * from '../components/identity-mark';
+export * from '../components/navigation-action';
+export * from '../components/progress';
+export * from '../components/select';
+export * from '../components/sidebar';
+export * from '../components/table';
+export * from '../components/textarea';
+export * from '../components/tooltip';
+export { cn } from '../lib/utils';
+//# sourceMappingURL=recipe-runtime.d.ts.map

package/dist/recipes/recipe-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe-runtime.d.ts","sourceRoot":"","sources":["../../src/recipes/recipe-runtime.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,oBAAoB,CAAA;AAClC,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,0BAA0B,CAAA;AACxC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,gCAAgC,CAAA;AAC9C,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA;AACpC,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almanaclabs/blaze-ui",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Shared React components and design tokens for Blaze",
   "type": "module",
   "sideEffects": [
@@ -8,6 +8,7 @@
   ],
   "files": [
     "dist",
+    "recipes",
     "src/styles",
     "README.md"
   ],

package/recipes/README.md

@@ -0,0 +1,24 @@
+# Recipes
+
+Recipes are executable reference implementations for designers and AI agents. They
+ship with the npm package and show how Blaze UI primitives combine into recognizable
+product surfaces without becoming part of the package's runtime API.
+
+Use a recipe when the page shares its anatomy and interaction model. Copy or adapt
+the composition into the application, replace fictional data, and connect links and
+actions through the application's framework conventions.
+
+Installed recipes are available under
+`node_modules/@almanaclabs/blaze-ui/recipes`. Start with `manifest.json` when
+discovering recipes programmatically.
+
+Preserve the recipe's semantic landmarks, responsive behavior, Blaze UI primitives,
+and semantic tokens. Do not copy fixture data or introduce application routing,
+authorization, serializers, or business rules into this directory.
+
+## Available recipes
+
+- [Workspace shell](workspace-shell/README.md): collapsible navigation, workspace
+  identity, page header, sub-navigation, account access, and a page-content slot.
+- [Guided workflow](guided-workflow/README.md): ordered step progress, contextual
+  work-item navigation, a focused canvas, and persistent workflow actions.

package/recipes/guided-workflow/README.md

@@ -0,0 +1,51 @@
+# Guided workflow recipe
+
+Use this recipe for multi-step creation and review experiences where people move
+between related work items, refine domain-specific content in a focused canvas,
+and advance through a gated sequence.
+
+## Preserve
+
+- A compact, ordered progress landmark with the active step marked by
+  `aria-current="step"`.
+- One controlled contextual rail for switching among sibling work items.
+- A single scrollable canvas for the selected item's domain content.
+- Back, secondary, status, and primary actions in a persistent workflow footer.
+- Responsive behavior that moves the rail above the canvas on smaller screens.
+- Semantic Blaze UI colors, spacing, focus treatment, and public components.
+- Divider-separated `GuidedWorkflowSection` blocks for task questions that share
+  one continuous canvas instead of behaving like standalone cards.
+
+## Adapt
+
+- Replace the fictional Storybook examples with serialized application data.
+- Keep step state, selected-item state, validation, and permissions in the app.
+- Compose forms, review tables, previews, and approval documents inside the
+  `children` canvas slot with public Blaze UI primitives.
+- Use `variant="compact"` when the workflow sits inside an established product
+  shell and needs the Blaze 3 title, compact stepper, canonical 340px rail, and
+  full-width white task canvas.
+- In `WorkspaceShellRecipe mode="focused"`, compose
+  `GuidedWorkflowPageHeader` into `pageHeader`, `GuidedWorkflowBody` into
+  `children`, and `GuidedWorkflowFooter` into `footer`. The workspace shell owns
+  the product identity row and its top-right exit action.
+- Pass only semantic or application-owned classes through `markerClassName`;
+  the section component owns marker geometry but not product category colors.
+- Connect callbacks to the application's routing and persistence conventions.
+- Use item statuses only for concise orientation; put actionable validation in
+  the canvas beside the field or object that needs attention.
+
+## Avoid
+
+- Importing this recipe as a runtime package component.
+- Moving forecasting, validation, approval policy, routing, or data fetching into
+  the copied recipe.
+- Turning channel-specific objects or third-party previews into recipe props.
+- Adding a second page shell around the recipe. Use the exported workflow regions
+  inside the application's existing authenticated shell; reserve the all-in-one
+  `GuidedWorkflowRecipe` for standalone examples and shell-less contexts.
+- Hiding required work behind color alone or allowing a disabled primary action
+  without nearby explanatory status text.
+
+Start from `guided-workflow.tsx`. Review `Recipes/Guided workflow` in Storybook for
+campaign-planning, workspace-onboarding, mobile, and dark-mode examples.

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

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "recipes": [
+    {
+      "name": "workspace-shell",
+      "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"
+    }
+  ]
+}