@brika/ui-kit 0.3.0

package/src/colors.ts

@@ -0,0 +1,99 @@
+/**
+ * Semantic color tokens for theme-aware brick styling.
+ *
+ * Tokens resolve to CSS custom-property references (`var(--color-…)`) that the
+ * browser evaluates at render time, so bricks automatically adapt to
+ * the active light / dark theme without any extra logic.
+ *
+ * Usage:
+ * ```tsx
+ * import { colors } from '@brika/ui-kit'
+ *
+ * <Text color={colors.mutedForeground}>Secondary text</Text>
+ * <Box background={colors.card}>Card surface</Box>
+ *
+ * // Or use shorthand token names — renderers resolve them automatically:
+ * <Text color="muted">Secondary text</Text>
+ * <Box background="card">Card surface</Box>
+ * ```
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Token types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Shorthand token names accepted by `color` props (text / icon context). */
+export type ColorToken =
+  | 'foreground'
+  | 'muted'
+  | 'primary'
+  | 'secondary'
+  | 'accent'
+  | 'card'
+  | 'destructive'
+  | 'success'
+  | 'warning'
+  | 'info'
+  | 'border';
+
+/** Shorthand token names accepted by `background` props (surface context). */
+export type BackgroundToken =
+  | 'background'
+  | 'card'
+  | 'muted'
+  | 'primary'
+  | 'secondary'
+  | 'accent'
+  | 'destructive';
+
+/** Value for a `color` prop — token name or any CSS color string. */
+export type ColorValue = ColorToken | (string & Record<never, never>);
+
+/** Value for a `background` prop — token name or any CSS color string. */
+export type BackgroundValue = BackgroundToken | (string & Record<never, never>);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Runtime color object (var() CSS references)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const colors = {
+  // Surface
+  background: 'var(--color-background)',
+  foreground: 'var(--color-foreground)',
+  card: 'var(--color-card)',
+  cardForeground: 'var(--color-card-foreground)',
+
+  // Interactive
+  primary: 'var(--color-primary)',
+  primaryForeground: 'var(--color-primary-foreground)',
+  secondary: 'var(--color-secondary)',
+  secondaryForeground: 'var(--color-secondary-foreground)',
+  muted: 'var(--color-muted)',
+  mutedForeground: 'var(--color-muted-foreground)',
+  accent: 'var(--color-accent)',
+  accentForeground: 'var(--color-accent-foreground)',
+
+  // Feedback
+  destructive: 'var(--color-destructive)',
+  destructiveForeground: 'var(--color-destructive-foreground)',
+  success: 'var(--color-success)',
+  successForeground: 'var(--color-success-foreground)',
+  warning: 'var(--color-warning)',
+  warningForeground: 'var(--color-warning-foreground)',
+  info: 'var(--color-info)',
+  infoForeground: 'var(--color-info-foreground)',
+
+  // UI elements
+  border: 'var(--color-border)',
+  ring: 'var(--color-ring)',
+
+  // Data visualization
+  data1: 'var(--color-data-1)',
+  data2: 'var(--color-data-2)',
+  data3: 'var(--color-data-3)',
+  data4: 'var(--color-data-4)',
+  data5: 'var(--color-data-5)',
+  data6: 'var(--color-data-6)',
+  data7: 'var(--color-data-7)',
+  data8: 'var(--color-data-8)',
+} as const;

package/src/define-brick.ts

@@ -0,0 +1,92 @@
+/**
+ * defineBrick — Brick Type Registration
+ *
+ * Plugins register brick **types** via `defineBrick()`. Each type can be placed
+ * multiple times on boards as independent **instances**, each with its own
+ * size (w/h grid units), config values, and isolated hooks state.
+ */
+
+import type { PreferenceDefinition } from '@brika/shared';
+import type { ComponentNode } from './nodes';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Supported brick size families (convention sizes for catalog display) */
+export type BrickFamily = 'sm' | 'md' | 'lg';
+
+/** Brick type spec — static metadata for type registration */
+export interface BrickTypeSpec {
+  id: string;
+  name?: string;
+  description?: string;
+  icon?: string;
+  color?: string;
+  category?: string;
+  /** Convention sizes for catalog display */
+  families: BrickFamily[];
+  /** Minimum grid size (default: { w: 1, h: 1 }) */
+  minSize?: { w: number; h: number };
+  /** Maximum grid size (default: { w: 12, h: 8 }) */
+  maxSize?: { w: number; h: number };
+  config?: PreferenceDefinition[];
+}
+
+/** Runtime context provided to each brick instance on every render */
+export interface BrickInstanceContext {
+  instanceId: string;
+  config: Record<string, unknown>;
+}
+
+/** Action handler receives optional payload from the UI */
+export type { ActionHandler as BrickActionHandler } from './nodes';
+
+/**
+ * Brick component function — called on every render.
+ * Receives instance context (config, instanceId).
+ * Use hooks (useState, useEffect, useBrickSize, etc.) inside.
+ * Pass handler functions directly to component props (onToggle, onPress, onChange).
+ * Returns JSX / ComponentNode(s) describing the brick body.
+ */
+export type BrickComponent = (ctx: BrickInstanceContext) => ComponentNode | ComponentNode[];
+
+/** Compiled brick type — ready for SDK registration */
+export interface CompiledBrickType {
+  spec: BrickTypeSpec;
+  component: BrickComponent;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// defineBrick
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Define a board brick type with hooks.
+ *
+ * @example
+ * ```tsx
+ * export const thermostat = defineBrick({
+ *   id: 'thermostat',
+ *   name: 'Thermostat',
+ *   icon: 'thermometer',
+ *   families: ['sm', 'md', 'lg'],
+ *   minSize: { w: 1, h: 1 },
+ *   maxSize: { w: 6, h: 6 },
+ * }, ({ config }) => {
+ *   const { width, height } = useBrickSize();
+ *   if (width <= 2 && height <= 2) {
+ *     return <Stat label="Temp" value="21.5°C" />;
+ *   }
+ *   return (
+ *     <>
+ *       <Stat label={config.room as string} value={21.5} unit="°C" />
+ *       <Toggle label="Heating" checked={heating} onToggle="toggle-heat" />
+ *     </>
+ *   );
+ * });
+ * ```
+ */
+export function defineBrick(spec: BrickTypeSpec, component: BrickComponent): CompiledBrickType {
+  return { spec, component };
+}

package/src/descriptors.ts

@@ -0,0 +1,28 @@
+import type { ComponentNode } from './nodes';
+
+export interface ActionNode {
+  id: string;
+  label?: string;
+  icon?: string;
+}
+
+export const MUT = { CREATE: 0, REPLACE: 1, UPDATE: 2, REMOVE: 3 } as const;
+
+export type Mutation =
+  | [op: 0, path: string, node: ComponentNode]
+  | [op: 1, path: string, node: ComponentNode]
+  | [op: 2, path: string, changes: Record<string, unknown>, removed?: string[]]
+  | [op: 3, path: string];
+
+export interface BrickDescriptor {
+  id: string;
+  title: string;
+  subtitle?: string;
+  icon?: string;
+  color?: string;
+  size: 'sm' | 'md' | 'lg' | 'xl';
+  body: ComponentNode[];
+  actions?: ActionNode[];
+  category?: string;
+  tags?: string[];
+}

package/src/index.ts

@@ -0,0 +1,154 @@
+/**
+ * @brika/ui-kit
+ *
+ * Descriptor types + component functions for plugin UI bricks.
+ * Zero React, zero DOM — consumed by both SDK (plugin-side) and UI app.
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Node Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type {
+  // Shared
+  ActionHandler,
+  AvatarNode,
+  BadgeNode,
+  BaseNode,
+  BoxNode,
+  // Input
+  ButtonNode,
+  // Feedback
+  CalloutNode,
+  ChartDataPoint,
+  ChartNode,
+  ChartSeries,
+  CheckboxNode,
+  CodeBlockNode,
+  ColumnNode,
+  ComponentNode,
+  DividerNode,
+  FlexLayoutProps,
+  GridNode,
+  // I18n + Intl
+  I18nRef,
+  IconNode,
+  ImageNode,
+  IntlRef,
+  KeyValueItem,
+  KeyValueNode,
+  LinkNode,
+  MarkdownNode,
+  NodeTypeMap,
+  ProgressNode,
+  // Layout
+  RowNode,
+  SectionNode,
+  SelectNode,
+  SelectOption,
+  SkeletonNode,
+  SliderNode,
+  SpacerNode,
+  StatusNode,
+  StatValueNode,
+  TabItem,
+  TableColumn,
+  TableNode,
+  TabsNode,
+  TextContent,
+  TextInputNode,
+  // Data display
+  TextNode,
+  ToggleNode,
+  VideoNode,
+} from './nodes';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Component Builders (PascalCase — used with custom jsx-runtime)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export {
+  Avatar,
+  Badge,
+  Box,
+  // Input
+  Button,
+  // Feedback
+  Callout,
+  Chart,
+  Checkbox,
+  CodeBlock,
+  Column,
+  Divider,
+  Grid,
+  Icon,
+  Image,
+  KeyValue,
+  Link,
+  Markdown,
+  Progress,
+  // Layout
+  Row,
+  Section,
+  Select,
+  Skeleton,
+  Slider,
+  Spacer,
+  Stat,
+  Status,
+  Table,
+  Tabs,
+  // Data display
+  Text,
+  TextInput,
+  Toggle,
+  Video,
+} from './nodes';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Descriptors
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type { ActionNode, BrickDescriptor, Mutation } from './descriptors';
+export { MUT } from './descriptors';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// defineBrick
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type {
+  BrickActionHandler,
+  BrickComponent,
+  BrickFamily,
+  BrickInstanceContext,
+  BrickTypeSpec,
+  CompiledBrickType,
+} from './define-brick';
+
+export { defineBrick } from './define-brick';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Mutation Applicator (shared between Hub and UI)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export { applyMutations } from './mutations';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Theme-aware color tokens
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type { BackgroundToken, BackgroundValue, ColorToken, ColorValue } from './colors';
+export { colors } from './colors';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Auto-action registration (internal — used by SDK render pipeline)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export {
+  _setActionRegistrar,
+  i18nRef,
+  intlRef,
+  isI18nRef,
+  isIntlRef,
+  resolveIntlRef,
+} from './nodes';

package/src/jsx-dev-runtime.ts

@@ -0,0 +1,3 @@
+// Dev mode re-export — Bun resolves jsx-dev-runtime in development
+// Dev mode uses jsxDEV instead of jsx/jsxs
+export { Fragment, type JSX, jsx as jsxDEV } from './jsx-runtime';

package/src/jsx-runtime.ts

@@ -0,0 +1,60 @@
+/**
+ * Custom JSX Runtime for BRIKA Card Descriptors
+ *
+ * Enables Raycast-style JSX DX in plugins:
+ *
+ *   ctx.update(
+ *     <>
+ *       <Section title="Status">
+ *         <Stat label="Temp" value={21} unit="°C" />
+ *       </Section>
+ *       <Toggle label="Heat" checked={on} onToggle="toggle" />
+ *     </>
+ *   );
+ *
+ * This is NOT React — JSX compiles to plain ComponentNode descriptors.
+ * Configure with: { "jsx": "react-jsx", "jsxImportSource": "@brika/ui-kit" }
+ */
+
+import type { ComponentNode } from './nodes';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// JSX Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+type NodeOrNodes = ComponentNode | ComponentNode[];
+
+export function jsx(
+  type: ((props: Record<string, unknown>) => NodeOrNodes) | typeof Fragment,
+  props: Record<string, unknown>,
+  _key?: string
+): NodeOrNodes {
+  return (type as (props: Record<string, unknown>) => NodeOrNodes)(props);
+}
+
+export const jsxs = jsx;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Fragment
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function Fragment(props: {
+  children?: NodeOrNodes | (NodeOrNodes | false | null | undefined)[];
+}): ComponentNode[] {
+  const { children } = props;
+  if (!children && children !== 0) return [];
+  if (!Array.isArray(children)) return [children as ComponentNode];
+  return (children as unknown[]).flat(Infinity).filter(Boolean) as ComponentNode[];
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// JSX Type Declarations
+// ─────────────────────────────────────────────────────────────────────────────
+
+export namespace JSX {
+  export type Element = ComponentNode | ComponentNode[];
+  export interface ElementChildrenAttribute {
+    children: {};
+  }
+  export interface IntrinsicElements {}
+}

package/src/mutations.ts

@@ -0,0 +1,79 @@
+import { MUT, type Mutation } from './descriptors';
+import type { ComponentNode } from './nodes';
+
+function hasChildren(node: ComponentNode): node is ComponentNode & { children: ComponentNode[] } {
+  return 'children' in node;
+}
+
+function applyChanges(
+  node: ComponentNode,
+  changes: Record<string, unknown>,
+  removed?: string[]
+): ComponentNode {
+  const updated = { ...node, ...changes };
+  if (removed) {
+    for (const k of removed) Reflect.deleteProperty(updated, k);
+  }
+  return updated;
+}
+
+export function applyMutations(body: ComponentNode[], mutations: Mutation[]): ComponentNode[] {
+  let result = body;
+  for (const m of mutations) {
+    result = applyOne(result, m);
+  }
+  return result;
+}
+
+function applyOne(body: ComponentNode[], mutation: Mutation): ComponentNode[] {
+  const segments = mutation[1].split('.').map(Number);
+  return updateAtPath(body, segments, 0, mutation);
+}
+
+function updateAtPath(
+  nodes: ComponentNode[],
+  segments: number[],
+  depth: number,
+  mutation: Mutation
+): ComponentNode[] {
+  const idx = segments[depth] ?? 0;
+  const isLeaf = depth === segments.length - 1;
+
+  if (isLeaf) {
+    switch (mutation[0]) {
+      case MUT.CREATE: {
+        const result = [...nodes];
+        if (idx >= result.length) {
+          result.push(mutation[2]);
+        } else {
+          result.splice(idx, 0, mutation[2]);
+        }
+        return result;
+      }
+      case MUT.REPLACE: {
+        const result = [...nodes];
+        result[idx] = mutation[2];
+        return result;
+      }
+      case MUT.UPDATE: {
+        const target = nodes[idx];
+        if (!target) return nodes;
+        const result = [...nodes];
+        result[idx] = applyChanges(target, mutation[2], mutation[3]);
+        return result;
+      }
+      case MUT.REMOVE: {
+        return nodes.filter((_, i) => i !== idx);
+      }
+    }
+  }
+
+  const node = nodes[idx];
+  if (!node || !hasChildren(node)) return nodes;
+
+  const updatedChildren = updateAtPath(node.children, segments, depth + 1, mutation);
+
+  const result = [...nodes];
+  result[idx] = { ...node, children: updatedChildren } as ComponentNode;
+  return result;
+}

package/src/nodes/_shared.ts

@@ -0,0 +1,129 @@
+/** Base fields shared by all component nodes */
+export interface BaseNode {
+  type: string;
+}
+
+// ── Marker type guard ────────────────────────────────────────────────────────
+
+function isMarker<T>(brand: string) {
+  return (v: unknown): v is T =>
+    v != null && typeof v === 'object' && (v as Record<string, unknown>)[brand] === true;
+}
+
+// ── I18n Reference ───────────────────────────────────────────────────────────
+
+export const i18nRef = (ns: string, key: string, params?: Record<string, string | number>) => ({
+  __i18n: true as const,
+  ns,
+  key,
+  params,
+});
+
+export type I18nRef = Readonly<ReturnType<typeof i18nRef>>;
+export const isI18nRef = isMarker<I18nRef>('__i18n');
+
+// ── Intl Reference ───────────────────────────────────────────────────────────
+
+export const intlRef = {
+  dateTime: (value: number, options?: Intl.DateTimeFormatOptions) => ({
+    __intl: true as const,
+    type: 'dateTime' as const,
+    value,
+    options,
+  }),
+  number: (value: number, options?: Intl.NumberFormatOptions) => ({
+    __intl: true as const,
+    type: 'number' as const,
+    value,
+    options,
+  }),
+  relativeTime: (value: number, unit: Intl.RelativeTimeFormatUnit) => ({
+    __intl: true as const,
+    type: 'relativeTime' as const,
+    value,
+    unit,
+  }),
+  list: (value: string[], options?: Intl.ListFormatOptions) => ({
+    __intl: true as const,
+    type: 'list' as const,
+    value,
+    options,
+  }),
+};
+
+export type IntlRef = {
+  [K in keyof typeof intlRef]: Readonly<ReturnType<(typeof intlRef)[K]>>;
+}[keyof typeof intlRef];
+export const isIntlRef = isMarker<IntlRef>('__intl');
+
+export function resolveIntlRef(ref: IntlRef, locale?: string): string {
+  if (!locale) return ref.type === 'list' ? ref.value.join(', ') : String(ref.value);
+  switch (ref.type) {
+    case 'dateTime':
+      return new Intl.DateTimeFormat(locale, ref.options).format(ref.value);
+    case 'number':
+      return new Intl.NumberFormat(locale, ref.options).format(ref.value);
+    case 'relativeTime':
+      return new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(ref.value, ref.unit);
+    case 'list':
+      return new Intl.ListFormat(
+        locale,
+        ref.options ?? { style: 'long', type: 'conjunction' }
+      ).format(ref.value);
+  }
+}
+
+export type TextContent = string | I18nRef | IntlRef;
+
+// ── Auto-action registration ─────────────────────────────────────────────────
+
+export type ActionHandler = (payload?: Record<string, unknown>) => void;
+
+let _registrar: ((handler: ActionHandler) => string) | null = null;
+let _fallbackIdx = 0;
+
+export function _setActionRegistrar(fn: ((handler: ActionHandler) => string) | null): void {
+  _registrar = fn;
+}
+
+export function resolveAction(handler: ActionHandler): string {
+  if (_registrar) return _registrar(handler);
+  return `__action_${_fallbackIdx++}`;
+}
+
+// ── Layout + Children ────────────────────────────────────────────────────────
+
+export interface FlexLayoutProps {
+  gap?: 'sm' | 'md' | 'lg';
+  align?: 'start' | 'center' | 'end' | 'stretch';
+  justify?: 'start' | 'center' | 'end' | 'between' | 'around';
+  wrap?: boolean;
+  grow?: boolean;
+  width?: string;
+  height?: string;
+}
+
+export interface NodeTypeMap {}
+export type ComponentNode = NodeTypeMap[keyof NodeTypeMap];
+export type Child = ComponentNode | I18nRef | IntlRef | ComponentNode[] | false | null | undefined;
+
+export function normalizeChildren(children: Child | Child[]): ComponentNode[] {
+  if (!children) return [];
+  const items = Array.isArray(children) ? children.flat() : [children];
+  const result: ComponentNode[] = [];
+  for (const c of items) {
+    if (c == null || c === false) continue;
+    if (isI18nRef(c)) {
+      result.push({
+        type: 'text',
+        content: c.key,
+        i18n: { ns: c.ns, key: c.key, params: c.params },
+      } as ComponentNode);
+    } else if (isIntlRef(c)) {
+      result.push({ type: 'text', content: resolveIntlRef(c), intl: c } as ComponentNode);
+    } else {
+      result.push(c);
+    }
+  }
+  return result;
+}

package/src/nodes/avatar.ts

@@ -0,0 +1,36 @@
+import { type ActionHandler, type BaseNode, resolveAction } from './_shared';
+
+export interface AvatarNode extends BaseNode {
+  type: 'avatar';
+  /** Image URL */
+  src?: string;
+  /** Fallback text (typically initials, e.g. "MS") */
+  fallback?: string;
+  /** Lucide icon name shown inside the avatar (overrides fallback text) */
+  icon?: string;
+  /** Background color for icon/fallback mode */
+  color?: string;
+  /** Accessible label */
+  alt?: string;
+  /** Display size */
+  size?: 'sm' | 'md' | 'lg';
+  /** Shape */
+  shape?: 'circle' | 'square';
+  /** Status indicator */
+  status?: 'online' | 'offline' | 'busy' | 'away';
+  /** Action dispatched when clicked */
+  onPress?: string;
+}
+
+export function Avatar(
+  props: Omit<AvatarNode, 'type' | 'onPress'> & { onPress?: ActionHandler }
+): AvatarNode {
+  const { onPress, ...rest } = props;
+  return { type: 'avatar', ...rest, onPress: onPress ? resolveAction(onPress) : undefined };
+}
+
+declare module './_shared' {
+  interface NodeTypeMap {
+    avatar: AvatarNode;
+  }
+}