@almanaclabs/blaze-ui 0.3.2 → 0.5.0

package/recipes/workspace-shell/README.md

@@ -0,0 +1,95 @@
+# Workspace shell recipe
+
+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 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"`.
+- 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 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.
+- 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; 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` 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>

package/recipes/workspace-shell/workspace-shell.css

@@ -0,0 +1,55 @@
+.workspace-shell-motion {
+  --workspace-shell-motion-duration: 150ms;
+  --workspace-shell-motion-easing: cubic-bezier(0.2, 0, 0, 1);
+}
+
+.workspace-shell-motion [data-slot='sidebar-gap'],
+.workspace-shell-motion [data-slot='sidebar-container'],
+.workspace-shell-motion [data-slot='sidebar-group-label'],
+.workspace-shell-motion [data-slot='sidebar-menu-button'] {
+  transition-duration: var(--workspace-shell-motion-duration);
+  transition-timing-function: var(--workspace-shell-motion-easing);
+}
+
+.workspace-shell-motion[data-sidebar-resizing] [data-slot='sidebar-gap'],
+.workspace-shell-motion[data-sidebar-resizing] [data-slot='sidebar-container'] {
+  transition-duration: 0ms;
+  will-change: width;
+}
+
+.workspace-navigation-label {
+  transition-property: opacity, transform;
+}
+
+.workspace-shell-motion
+  [data-slot='sidebar'][data-state='collapsed']
+  .workspace-navigation-label,
+.workspace-shell-motion
+  [data-slot='sidebar'][data-state='collapsed']
+  [data-slot='sidebar-group-label'] {
+  transition-delay: 0ms;
+  transition-duration: 90ms;
+  transition-timing-function: cubic-bezier(0.3, 0, 0.8, 0.15);
+}
+
+.workspace-shell-motion
+  [data-slot='sidebar'][data-state='expanded']
+  .workspace-navigation-label,
+.workspace-shell-motion
+  [data-slot='sidebar'][data-state='expanded']
+  [data-slot='sidebar-group-label'] {
+  transition-delay: 20ms;
+  transition-duration: 130ms;
+  transition-timing-function: cubic-bezier(0.05, 0.7, 0.1, 1);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .workspace-shell-motion [data-slot='sidebar-gap'],
+  .workspace-shell-motion [data-slot='sidebar-container'],
+  .workspace-shell-motion [data-slot='sidebar-group-label'],
+  .workspace-shell-motion [data-slot='sidebar-menu-button'],
+  .workspace-shell-motion .workspace-navigation-label {
+    transition-delay: 0ms !important;
+    transition-duration: 0ms !important;
+  }
+}