@almanaclabs/blaze-ui 0.3.1 → 0.4.0

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,6 @@
+export * from '../components/avatar';
+export * from '../components/button';
+export * from '../components/dropdown-menu';
+export * from '../components/sidebar';
+export * from '../components/tooltip';
+//# 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,qBAAqB,CAAA;AACnC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almanaclabs/blaze-ui",
-  "version": "0.3.1",
+  "version": "0.4.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,22 @@
+# 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.

package/recipes/manifest.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "recipes": [
+    {
+      "name": "workspace-shell",
+      "description": "Authenticated Blaze workspace chrome with access-mode theming, navigation, and an empty page-content slot.",
+      "dependencies": ["@almanaclabs/blaze-ui", "@tabler/icons-react"],
+      "entry": "workspace-shell/workspace-shell.tsx",
+      "instructions": "workspace-shell/README.md"
+    }
+  ]
+}

package/recipes/workspace-shell/README.md

@@ -0,0 +1,41 @@
+# 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.
+
+## Preserve
+
+- One `SidebarProvider` wrapping the sidebar and inset.
+- Primary and settings navigation landmarks with an active item 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.
+
+## 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 `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.
+
+## 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.
+
+Start from `workspace-shell.tsx`. Use the hosted Storybook
+`Recipes/Workspace shell` entry to review expanded, collapsed, AM-mode, client-mode,
+and mobile states.

package/recipes/workspace-shell/workspace-shell.tsx

@@ -0,0 +1,386 @@
+import type { ComponentProps, ComponentType, ReactNode } from 'react'
+import {
+  IconArrowsUpDown,
+  IconBolt,
+  IconBrowser,
+  IconChartBar,
+  IconHome,
+  IconLogout,
+  IconSearch,
+  IconSettings,
+  IconStar,
+  IconTags,
+  IconTarget,
+  IconUser,
+  IconUsers,
+  IconWorld,
+} from '@tabler/icons-react'
+
+import {
+  Avatar,
+  AvatarFallback,
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarProvider,
+  SidebarRail,
+  SidebarTrigger,
+  TooltipProvider,
+} from '@almanaclabs/blaze-ui'
+
+type NavigationIcon = ComponentType<{
+  className?: string
+  'aria-hidden'?: boolean | 'true' | 'false'
+}>
+
+export type WorkspaceShellNavigationItem = {
+  key: string
+  label: string
+  href: string
+  icon: NavigationIcon
+}
+
+export type WorkspaceShellSubNavigationItem = {
+  key: string
+  label: string
+  href: string
+}
+
+export type WorkspaceShellRecipeProps = {
+  title: string
+  workspaceName: string
+  userEmail: string
+  activeNavigationKey: string
+  activeSubNavigationKey?: string
+  accessMode?: 'am' | 'client'
+  children?: ReactNode
+  defaultSidebarOpen?: boolean
+  subNavigation?: readonly WorkspaceShellSubNavigationItem[]
+}
+
+const primaryNavigation: readonly WorkspaceShellNavigationItem[] = [
+  { key: 'home', label: 'Home', href: '#home', icon: IconHome },
+  {
+    key: 'analytics',
+    label: 'Analytics',
+    href: '#analytics',
+    icon: IconChartBar,
+  },
+  {
+    key: 'integrations',
+    label: 'Integrations',
+    href: '#integrations',
+    icon: IconBolt,
+  },
+  { key: 'brand-kit', label: 'Brand Kit', href: '#brand-kit', icon: IconTags },
+  {
+    key: 'scorecard',
+    label: 'Scorecard',
+    href: '#scorecard',
+    icon: IconTarget,
+  },
+]
+
+const channelNavigation: readonly WorkspaceShellNavigationItem[] = [
+  {
+    key: 'google-ads',
+    label: 'Google Ads',
+    href: '#google-ads',
+    icon: IconSearch,
+  },
+  { key: 'seo-aeo', label: 'SEO/AEO', href: '#seo-aeo', icon: IconWorld },
+  { key: 'website', label: 'Website', href: '#website', icon: IconBrowser },
+  {
+    key: 'reputation',
+    label: 'Reputation',
+    href: '#reputation',
+    icon: IconStar,
+  },
+  {
+    key: 'inbound-sdr',
+    label: 'Inbound SDR',
+    href: '#inbound-sdr',
+    icon: IconUsers,
+  },
+]
+
+function initials(value: string) {
+  return value
+    .split(/\s+|@/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map((part) => part[0]?.toUpperCase())
+    .join('')
+}
+
+function RecipeLink({
+  href,
+  children,
+  ...props
+}: ComponentProps<'a'> & { href: string }) {
+  return (
+    <a href={href} onClick={(event) => event.preventDefault()} {...props}>
+      {children}
+    </a>
+  )
+}
+
+function WorkspaceSelector({ workspaceName }: { workspaceName: string }) {
+  return (
+    <SidebarMenu>
+      <SidebarMenuItem>
+        <DropdownMenu>
+          <DropdownMenuTrigger
+            render={
+              <SidebarMenuButton
+                size="lg"
+                aria-label={`Open workspace menu for ${workspaceName}`}
+                className="data-[popup-open]:bg-sidebar-accent data-[popup-open]:text-sidebar-accent-foreground"
+              />
+            }
+          >
+            <span className="flex aspect-square size-8 items-center justify-center rounded-lg bg-sidebar-primary font-semibold text-sidebar-primary-foreground">
+              {initials(workspaceName).slice(0, 1)}
+            </span>
+            <span className="grid flex-1 text-left text-sm leading-tight">
+              <span className="truncate font-medium">{workspaceName}</span>
+              <span className="truncate text-xs text-sidebar-foreground/65">
+                Client workspace
+              </span>
+            </span>
+            <IconArrowsUpDown className="ml-auto" aria-hidden="true" />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="start" side="right" className="min-w-56">
+            <DropdownMenuGroup>
+              <DropdownMenuLabel>Workspace</DropdownMenuLabel>
+              <DropdownMenuItem>
+                <IconUsers aria-hidden="true" />
+                All workspaces
+              </DropdownMenuItem>
+            </DropdownMenuGroup>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem>
+              <IconLogout aria-hidden="true" />
+              Sign out
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </SidebarMenuItem>
+    </SidebarMenu>
+  )
+}
+
+function NavigationGroup({
+  items,
+  activeKey,
+  label,
+}: {
+  items: readonly WorkspaceShellNavigationItem[]
+  activeKey: string
+  label?: string
+}) {
+  return (
+    <SidebarGroup>
+      {label && <SidebarGroupLabel>{label}</SidebarGroupLabel>}
+      <SidebarGroupContent>
+        <SidebarMenu>
+          {items.map((item) => (
+            <SidebarMenuItem key={item.key}>
+              <SidebarMenuButton
+                tooltip={item.label}
+                isActive={item.key === activeKey}
+                render={
+                  <RecipeLink
+                    href={item.href}
+                    aria-current={item.key === activeKey ? 'page' : undefined}
+                  />
+                }
+              >
+                <item.icon aria-hidden="true" />
+                <span>{item.label}</span>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          ))}
+        </SidebarMenu>
+      </SidebarGroupContent>
+    </SidebarGroup>
+  )
+}
+
+function AccountMenu({ userEmail }: { userEmail: string }) {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        render={
+          <Button
+            variant="ghost"
+            size="icon"
+            aria-label={`Open account menu. Signed in as ${userEmail}`}
+            className="rounded-full"
+          />
+        }
+      >
+        <Avatar size="sm">
+          <AvatarFallback>{initials(userEmail)}</AvatarFallback>
+        </Avatar>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="min-w-56">
+        <DropdownMenuGroup>
+          <DropdownMenuLabel>{userEmail}</DropdownMenuLabel>
+        </DropdownMenuGroup>
+        <DropdownMenuSeparator />
+        <DropdownMenuGroup>
+          <DropdownMenuItem>
+            <IconUser aria-hidden="true" />
+            Account settings
+          </DropdownMenuItem>
+        </DropdownMenuGroup>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem>
+          <IconLogout aria-hidden="true" />
+          Sign out
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+export function WorkspaceShellRecipe({
+  title,
+  workspaceName,
+  userEmail,
+  activeNavigationKey,
+  activeSubNavigationKey,
+  children,
+  accessMode = 'client',
+  defaultSidebarOpen = true,
+  subNavigation = [],
+}: WorkspaceShellRecipeProps) {
+  const darkSidebar = accessMode === 'client'
+  const sidebarTheme = darkSidebar ? 'dark' : 'light'
+
+  return (
+    <TooltipProvider>
+      <SidebarProvider
+        defaultOpen={defaultSidebarOpen}
+        className="min-h-[720px]"
+      >
+        <Sidebar collapsible="icon">
+          <div
+            className={`${darkSidebar ? 'dark' : ''} flex min-h-0 flex-1 flex-col bg-sidebar text-sidebar-foreground`}
+            data-sidebar-theme={sidebarTheme}
+          >
+            <SidebarHeader className="border-b border-sidebar-border p-2">
+              <WorkspaceSelector workspaceName={workspaceName} />
+            </SidebarHeader>
+            <SidebarContent>
+              <nav aria-label="Primary">
+                <NavigationGroup
+                  items={primaryNavigation}
+                  activeKey={activeNavigationKey}
+                />
+                <NavigationGroup
+                  items={channelNavigation}
+                  activeKey={activeNavigationKey}
+                  label="Channels"
+                />
+              </nav>
+            </SidebarContent>
+            <SidebarFooter className="p-2">
+              <nav aria-label="Settings">
+                <SidebarMenu>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton
+                      tooltip="Settings"
+                      isActive={activeNavigationKey === 'settings'}
+                      render={
+                        <RecipeLink
+                          href="#settings"
+                          aria-current={
+                            activeNavigationKey === 'settings'
+                              ? 'page'
+                              : undefined
+                          }
+                        />
+                      }
+                    >
+                      <IconSettings aria-hidden="true" />
+                      <span>Settings</span>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                </SidebarMenu>
+              </nav>
+            </SidebarFooter>
+          </div>
+          <SidebarRail />
+        </Sidebar>
+
+        <SidebarInset className="min-w-0">
+          <header className="sticky top-0 z-20 shrink-0 border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/80">
+            <div className="grid min-h-16 grid-cols-[minmax(0,1fr)_auto] items-center gap-3 px-4 transition-[min-height] group-has-data-[collapsible=icon]/sidebar-wrapper:min-h-12 md:grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] md:px-6">
+              <div className="col-start-1 row-start-1 flex min-w-0 items-center gap-2">
+                <SidebarTrigger className="-ml-2 shrink-0" />
+                <h1 className="truncate text-lg font-semibold tracking-tight">
+                  {title}
+                </h1>
+              </div>
+
+              {subNavigation.length > 0 && (
+                <nav
+                  aria-label="Page"
+                  className="col-span-2 col-start-1 row-start-2 -mx-4 overflow-x-auto border-t px-4 md:col-span-1 md:col-start-2 md:row-start-1 md:mx-0 md:overflow-visible md:border-0 md:px-0"
+                >
+                  <ul className="flex min-w-max items-center justify-center gap-1">
+                    {subNavigation.map((item) => {
+                      const active = item.key === activeSubNavigationKey
+
+                      return (
+                        <li key={item.key}>
+                          <Button
+                            aria-current={active ? 'page' : undefined}
+                            nativeButton={false}
+                            render={<RecipeLink href={item.href} />}
+                            role="link"
+                            size="sm"
+                            variant={active ? 'secondary' : 'ghost'}
+                          >
+                            {item.label}
+                          </Button>
+                        </li>
+                      )
+                    })}
+                  </ul>
+                </nav>
+              )}
+
+              <div className="col-start-2 row-start-1 flex items-center gap-2 justify-self-end md:col-start-3">
+                <Button variant="outline" size="sm">
+                  {accessMode === 'client' ? 'Client' : 'AM'}
+                </Button>
+                <AccountMenu userEmail={userEmail} />
+              </div>
+            </div>
+          </header>
+
+          <div className="flex-1 p-4 md:p-6">{children}</div>
+        </SidebarInset>
+      </SidebarProvider>
+    </TooltipProvider>
+  )
+}

package/src/styles/globals.css

@@ -168,6 +168,11 @@
     background-color: var(--background);
     color: var(--foreground);
   }
+
+  button:not(:disabled):not([aria-disabled='true']),
+  [role='button']:not(:disabled):not([aria-disabled='true']) {
+    cursor: pointer;
+  }
 }
 
 @media (prefers-reduced-motion: reduce) {