@polderlabs/bizar 7.0.2 → 8.0.0

package/bizar-dash/src/web/v8/ui/primitives/ScrollArea.tsx

@@ -0,0 +1,62 @@
+import { forwardRef, type CSSProperties, type HTMLAttributes, type ReactNode } from 'react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * ScrollArea — a styled scroll container.
+ *
+ * The browser-native scrollbar is themed via globals.css (--border-strong,
+ * --bg). Use this primitive when you want scroll containment with the
+ * v8 look-and-feel and a stable scroll shadow at the edges.
+ *
+ * For Kanban columns (which need horizontal scrolling with sticky shadows),
+ * prefer the dedicated KanbanColumn surface (added in Sprint S5).
+ */
+export interface ScrollAreaProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** Direction of overflow. Default 'y' (vertical scroll). */
+  direction?: 'x' | 'y' | 'both';
+  /** Show a fading shadow at the top when scrolled down. */
+  shadowTop?: boolean;
+  /** Show a fading shadow at the bottom when content overflows. */
+  shadowBottom?: boolean;
+  /** Maximum height (e.g. '400px', 'calc(100vh - 200px)'). */
+  maxHeight?: string;
+  /** Maximum width. */
+  maxWidth?: string;
+  children?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export const ScrollArea = forwardRef<HTMLDivElement, ScrollAreaProps>(function ScrollArea(
+  props,
+  ref,
+) {
+  const {
+    direction = 'y',
+    shadowTop,
+    shadowBottom,
+    maxHeight,
+    maxWidth,
+    children,
+    className,
+    style,
+    ...rest
+  } = props;
+
+  const overflowX = direction === 'x' || direction === 'both' ? 'auto' : 'hidden';
+  const overflowY = direction === 'y' || direction === 'both' ? 'auto' : 'hidden';
+
+  const computedStyle: CSSProperties = {
+    overflowX,
+    overflowY,
+    ...(maxHeight !== undefined && { maxHeight }),
+    ...(maxWidth !== undefined && { maxWidth }),
+    ...style,
+  };
+
+  return (
+    <div ref={ref} className={cx('v8-scroll-area', className)} style={computedStyle} {...rest}>
+      {children}
+    </div>
+  );
+});

package/bizar-dash/src/web/v8/ui/primitives/Separator.tsx

@@ -0,0 +1,42 @@
+import { forwardRef, type CSSProperties, type HTMLAttributes } from 'react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * Separator — a 1px divider, either horizontal or vertical.
+ *
+ * Renders as `<div role="separator">`. Use `decorative` to suppress the
+ * role for purely visual dividers (still announces for AT).
+ */
+export interface SeparatorProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
+  orientation?: 'horizontal' | 'vertical';
+  /** When true, treat as decorative — sets `role="presentation"` and aria-hidden. */
+  decorative?: boolean;
+  /** Token-based color override. */
+  tone?: 'border' | 'border-strong';
+  className?: string;
+  style?: CSSProperties;
+}
+
+export const Separator = forwardRef<HTMLDivElement, SeparatorProps>(function Separator(props, ref) {
+  const { orientation = 'horizontal', decorative, tone = 'border', className, style, ...rest } = props;
+
+  const computedStyle: CSSProperties = {
+    background: `var(--${tone})`,
+    ...(orientation === 'horizontal'
+      ? { height: '1px', width: '100%' }
+      : { width: '1px', height: '100%', alignSelf: 'stretch' }),
+    ...style,
+  };
+
+  return (
+    <div
+      ref={ref}
+      role={decorative ? 'presentation' : 'separator'}
+      aria-orientation={decorative ? undefined : orientation}
+      aria-hidden={decorative ? 'true' : undefined}
+      className={cx('v8-separator', className)}
+      style={computedStyle}
+      {...rest}
+    />
+  );
+});

package/bizar-dash/src/web/v8/ui/primitives/Stack.tsx

@@ -0,0 +1,73 @@
+import { forwardRef, type ElementType, type HTMLAttributes, type ReactNode } from 'react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * Stack — vertical flexbox column with token-driven gap and align.
+ *
+ * Use this for the 90% case of "I need a column of stuff with space
+ * between them". For horizontal use Inline/Cluster; for grid use Grid.
+ */
+export interface StackProps extends HTMLAttributes<HTMLElement> {
+  as?: ElementType;
+  /** Gap — uses --space-* tokens. */
+  gap?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16;
+  align?: 'start' | 'center' | 'end' | 'stretch';
+  justify?: 'start' | 'center' | 'end' | 'between' | 'around';
+  wrap?: boolean;
+  children?: ReactNode;
+  className?: string;
+}
+
+const SPACE_VAR: Record<NonNullable<StackProps['gap']>, string> = {
+  0: '0',
+  1: 'var(--space-1)',
+  2: 'var(--space-2)',
+  3: 'var(--space-3)',
+  4: 'var(--space-4)',
+  5: 'var(--space-5)',
+  6: 'var(--space-6)',
+  8: 'var(--space-8)',
+  10: 'var(--space-10)',
+  12: 'var(--space-12)',
+  16: 'var(--space-16)',
+};
+
+const ALIGN_MAP = { start: 'flex-start', center: 'center', end: 'flex-end', stretch: 'stretch' } as const;
+const JUSTIFY_MAP = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  between: 'space-between',
+  around: 'space-around',
+} as const;
+
+export const Stack = forwardRef<HTMLElement, StackProps>(function Stack(props, ref) {
+  const {
+    as,
+    gap = 3,
+    align,
+    justify,
+    wrap,
+    children,
+    className,
+    style,
+    ...rest
+  } = props;
+
+  const Tag = (as ?? 'div') as ElementType;
+  const computedStyle: React.CSSProperties = {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: SPACE_VAR[gap],
+    ...(align !== undefined && { alignItems: ALIGN_MAP[align] }),
+    ...(justify !== undefined && { justifyContent: JUSTIFY_MAP[justify] }),
+    ...(wrap && { flexWrap: 'wrap' }),
+    ...style,
+  };
+
+  return (
+    <Tag ref={ref} className={cx('v8-stack', className)} style={computedStyle} {...rest}>
+      {children}
+    </Tag>
+  );
+});

package/bizar-dash/src/web/v8/ui/primitives/VisuallyHidden.tsx

@@ -0,0 +1,49 @@
+import { type ElementType, type ReactNode } from 'react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * VisuallyHidden — hide content visually while keeping it accessible to
+ * screen readers and search engines.
+ *
+ * Use for:
+ *   - Labels on icon-only buttons (`<IconButton aria-label="…" />`)
+ *   - "Skip to main content" links
+ *   - Accessible names for icon groups
+ */
+export interface VisuallyHiddenProps {
+  as?: ElementType;
+  children: ReactNode;
+  className?: string;
+  /** Render visibly if true (debug helper — NEVER true in production code). */
+  forceVisible?: boolean;
+}
+
+export function VisuallyHidden({
+  as,
+  children,
+  className,
+  forceVisible,
+}: VisuallyHiddenProps): JSX.Element {
+  const Tag = (as ?? 'span') as ElementType;
+  if (forceVisible === true) {
+    return <Tag className={className}>{children}</Tag>;
+  }
+  return (
+    <Tag
+      className={cx('v8-visually-hidden', className)}
+      style={{
+        position: 'absolute',
+        width: '1px',
+        height: '1px',
+        padding: 0,
+        margin: '-1px',
+        overflow: 'hidden',
+        clip: 'rect(0, 0, 0, 0)',
+        whiteSpace: 'nowrap',
+        border: 0,
+      }}
+    >
+      {children}
+    </Tag>
+  );
+}

package/bizar-dash/src/web/v8/ui/settings/SettingsNav.tsx

@@ -0,0 +1,91 @@
+import { type ReactNode } from 'react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * SettingsNav — left rail inside the Settings page.
+ *
+ * Lists each section so the user can jump (or scroll) to it. The active
+ * section is highlighted. The nav is a vertical list with section ids
+ * as the anchor target; no JS router needed.
+ */
+
+export interface SettingsNavItem {
+  id: string;
+  title: string;
+  icon?: ReactNode;
+}
+
+export interface SettingsNavProps {
+  items: readonly SettingsNavItem[];
+  /** The id of the currently-visible section. */
+  activeId?: string;
+  /** Click handler — usually `() => document.getElementById(id)?.scrollIntoView()`. */
+  onSelect?: (id: string) => void;
+  className?: string;
+}
+
+export function SettingsNav(props: SettingsNavProps) {
+  const { items, activeId, onSelect, className } = props;
+  return (
+    <nav aria-label="Settings sections" className={cx('v8-settings-nav', className)}>
+      <ul
+        style={{
+          listStyle: 'none',
+          margin: 0,
+          padding: 0,
+          display: 'flex',
+          flexDirection: 'column',
+          gap: 2,
+        }}
+      >
+        {items.map((item) => {
+          const isActive = activeId === item.id;
+          return (
+            <li key={item.id}>
+              <button
+                type="button"
+                onClick={() => onSelect?.(item.id)}
+                aria-current={isActive ? 'true' : undefined}
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 'var(--space-2)',
+                  width: '100%',
+                  padding: 'var(--space-2) var(--space-3)',
+                  background: isActive ? 'var(--surface-2)' : 'transparent',
+                  border: 0,
+                  borderRadius: 'var(--radius-sm)',
+                  color: isActive ? 'var(--fg)' : 'var(--fg-muted)',
+                  font: 'inherit',
+                  fontSize: 'var(--fs-13)',
+                  fontWeight: isActive ? 500 : 400,
+                  cursor: 'pointer',
+                  textAlign: 'left',
+                }}
+              >
+                {item.icon !== undefined && (
+                  <span
+                    aria-hidden="true"
+                    style={{
+                      display: 'inline-flex',
+                      color: isActive ? 'var(--accent)' : 'var(--fg-subtle)',
+                      flexShrink: 0,
+                    }}
+                  >
+                    {item.icon}
+                  </span>
+                )}
+                <span style={{ minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                  {item.title}
+                </span>
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+      <style>{`
+        .v8-settings-nav button:hover { background: var(--surface-2); color: var(--fg); }
+      `}</style>
+    </nav>
+  );
+}

package/bizar-dash/src/web/v8/ui/settings/SettingsRow.tsx

@@ -0,0 +1,88 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * SettingsRow — one labelled option inside a SettingsSection.
+ *
+ * Three-column layout:
+ *   ┌─ label + description ────────────  control  ─┐
+ * The label column is required; the control slot
+ * hosts the actual interactive (Switch, Select, Slider, custom button, etc.).
+ */
+
+export interface SettingsRowProps extends HTMLAttributes<HTMLDivElement> {
+  id: string;
+  /** The control label (left column). */
+  label: ReactNode;
+  /** Optional one-line description (left column, below label). */
+  description?: ReactNode;
+  /** Right column — the interactive control. */
+  control: ReactNode;
+  /** Mark the row as disabled (visual + aria). */
+  disabled?: boolean;
+}
+
+export const SettingsRow = forwardRef<HTMLDivElement, SettingsRowProps>(function SettingsRow(
+  props,
+  ref,
+) {
+  const { id, label, description, control, disabled = false, className, ...rest } = props;
+  // The label is announced via `aria-labelledby` rather than `<label
+  // htmlFor>` because the control is generic — its DOM id is set by the
+  // consumer (Switch, Select, custom input), and we'd otherwise need to
+  // thread it through the props chain. `aria-labelledby` is the WAI-ARIA
+  // sanctioned way to label a region without owning a native `<label>`.
+  const labelId = `${id}-label`;
+  return (
+    <div
+      ref={ref}
+      data-disabled={disabled || undefined}
+      aria-disabled={disabled || undefined}
+      className={cx('v8-settings-row', className)}
+      style={{
+        display: 'flex',
+        alignItems: 'flex-start',
+        justifyContent: 'space-between',
+        gap: 'var(--space-4)',
+        padding: 'var(--space-3) 0',
+        borderBottom: '1px solid var(--border)',
+        opacity: disabled ? 0.5 : 1,
+      }}
+      {...rest}
+    >
+      <div id={labelId} style={{ flex: 1, minWidth: 0 }}>
+        <span
+          style={{
+            display: 'block',
+            fontSize: 'var(--fs-13)',
+            fontWeight: 500,
+            color: 'var(--fg)',
+            cursor: disabled ? 'not-allowed' : 'default',
+            lineHeight: 'var(--lh-snug)',
+          }}
+        >
+          {label}
+        </span>
+        {description !== undefined && (
+          <p
+            style={{
+              fontSize: 'var(--fs-12)',
+              color: 'var(--fg-muted)',
+              margin: '4px 0 0 0',
+              lineHeight: 'var(--lh-snug)',
+            }}
+          >
+            {description}
+          </p>
+        )}
+      </div>
+      <div
+        role="group"
+        aria-labelledby={labelId}
+        style={{ flexShrink: 0, alignSelf: 'center' }}
+      >
+        {control}
+      </div>
+    </div>
+  );
+});

package/bizar-dash/src/web/v8/ui/settings/SettingsSection.tsx

@@ -0,0 +1,109 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * SettingsSection — a titled, optionally-described section of the Settings
+ * page.
+ *
+ * PLAN.md §Settings declares 16 sections; SettingsSection is the shell
+ * they all use. The body is a free slot so each section composes its own
+ * option rows (SettingsRow) and sub-sections.
+ */
+
+export interface SettingsSectionProps extends HTMLAttributes<HTMLElement> {
+  id: string;
+  title: string;
+  /** One-sentence summary of what this section controls. */
+  description?: string;
+  /** Optional icon (lucide). */
+  icon?: ReactNode;
+  /** Section body — SettingsRow, sub-sections, etc. */
+  children?: ReactNode;
+  /** Right-aligned header slot (e.g. "Restore defaults" button). */
+  headerActions?: ReactNode;
+}
+
+export const SettingsSection = forwardRef<HTMLElement, SettingsSectionProps>(function SettingsSection(
+  props,
+  ref,
+) {
+  const { id, title, description, icon, children, headerActions, className, ...rest } = props;
+  return (
+    <section
+      ref={ref}
+      id={id}
+      aria-labelledby={`${id}-title`}
+      className={cx('v8-settings-section', className)}
+      style={{
+        padding: 'var(--space-5) var(--space-6)',
+        background: 'var(--surface-1)',
+        border: '1px solid var(--border)',
+        borderRadius: 'var(--radius-lg)',
+      }}
+      {...rest}
+    >
+      <header
+        style={{
+          display: 'flex',
+          alignItems: 'flex-start',
+          justifyContent: 'space-between',
+          gap: 'var(--space-3)',
+          marginBottom: 'var(--space-4)',
+        }}
+      >
+        <div style={{ display: 'flex', alignItems: 'flex-start', gap: 'var(--space-3)', minWidth: 0 }}>
+          {icon !== undefined && (
+            <span
+              aria-hidden="true"
+              style={{
+                display: 'inline-flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                width: 28,
+                height: 28,
+                borderRadius: 'var(--radius-sm)',
+                background: 'color-mix(in oklch, var(--accent) 14%, transparent)',
+                color: 'var(--accent)',
+                flexShrink: 0,
+              }}
+            >
+              {icon}
+            </span>
+          )}
+          <div style={{ minWidth: 0 }}>
+            <h2
+              id={`${id}-title`}
+              style={{
+                fontSize: 'var(--fs-15)',
+                fontWeight: 600,
+                color: 'var(--fg)',
+                lineHeight: 'var(--lh-snug)',
+                margin: 0,
+              }}
+            >
+              {title}
+            </h2>
+            {description !== undefined && (
+              <p
+                style={{
+                  fontSize: 'var(--fs-13)',
+                  color: 'var(--fg-muted)',
+                  margin: '4px 0 0 0',
+                  lineHeight: 'var(--lh-snug)',
+                }}
+              >
+                {description}
+              </p>
+            )}
+          </div>
+        </div>
+        {headerActions !== undefined && (
+          <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--space-2)', flexShrink: 0 }}>
+            {headerActions}
+          </div>
+        )}
+      </header>
+      <div className="v8-settings-section__body">{children}</div>
+    </section>
+  );
+});