@moldable-ai/ui 0.2.29 → 0.2.32

package/src/tokens/contracts.ts

@@ -0,0 +1,131 @@
+export type UITheme = 'platform' | 'moldable'
+
+export type UIPlatform = 'macos' | 'windows' | 'web'
+
+export type UIPlatformVersion = string
+
+/**
+ * A component recipe can intentionally come from a different versioned
+ * platform source than the application's base platform pack.
+ *
+ * Public names describe the anatomy an app is choosing. The registry below
+ * records which immutable platform source defines each recipe.
+ */
+export type UISidebarStyle = 'platform' | 'floating' | 'edge-to-edge'
+
+export type PlatformPackId = `${UIPlatform}-${string}`
+
+export interface UIPlatformPack {
+  id: PlatformPackId
+  platform: UIPlatform
+  version: UIPlatformVersion
+  capabilities: {
+    nativeMaterials: boolean
+    nativeWindowChrome: boolean
+    overlayScrollbars: boolean
+  }
+}
+
+export type UIAppearance = 'light' | 'dark' | 'system'
+
+export type ResolvedUIAppearance = Exclude<UIAppearance, 'system'>
+
+export type ControlSize = 'mini' | 'small' | 'medium' | 'large' | 'xl'
+
+export type LayoutDensity = 'compact' | 'regular' | 'comfortable'
+
+export type MaterialThickness =
+  | 'ultra-thick'
+  | 'thick'
+  | 'medium'
+  | 'thin'
+  | 'ultra-thin'
+
+export type MaterialContext = 'content' | 'over-glass'
+
+export type ContrastPreference = 'system' | 'standard' | 'increased'
+
+export type TransparencyPreference = 'system' | 'standard' | 'reduced'
+
+export type MotionPreference = 'system' | 'standard' | 'reduced'
+
+export interface UIPreferences {
+  contrast?: ContrastPreference
+  transparency?: TransparencyPreference
+  motion?: MotionPreference
+}
+
+export const CONTROL_SIZES = [
+  'mini',
+  'small',
+  'medium',
+  'large',
+  'xl',
+] as const satisfies readonly ControlSize[]
+
+export const MATERIAL_THICKNESSES = [
+  'ultra-thick',
+  'thick',
+  'medium',
+  'thin',
+  'ultra-thin',
+] as const satisfies readonly MaterialThickness[]
+
+export const SIDEBAR_STYLES = {
+  platform: {
+    id: 'platform',
+    sourcePlatform: null,
+    sourceVersion: null,
+  },
+  floating: {
+    id: 'floating',
+    sourcePlatform: 'macos',
+    sourceVersion: '26',
+  },
+  'edge-to-edge': {
+    id: 'edge-to-edge',
+    sourcePlatform: 'macos',
+    sourceVersion: '27',
+  },
+} as const satisfies Record<
+  UISidebarStyle,
+  {
+    id: UISidebarStyle
+    sourcePlatform: UIPlatform | null
+    sourceVersion: UIPlatformVersion | null
+  }
+>
+
+export const PLATFORM_PACKS = {
+  'macos-27': {
+    id: 'macos-27',
+    platform: 'macos',
+    version: '27',
+    capabilities: {
+      nativeMaterials: true,
+      nativeWindowChrome: true,
+      overlayScrollbars: true,
+    },
+  },
+  'web-default': {
+    id: 'web-default',
+    platform: 'web',
+    version: 'default',
+    capabilities: {
+      nativeMaterials: false,
+      nativeWindowChrome: false,
+      overlayScrollbars: false,
+    },
+  },
+} as const satisfies Record<string, UIPlatformPack>
+
+export function resolvePlatformPack(
+  platform: UIPlatform,
+  version: UIPlatformVersion,
+): UIPlatformPack {
+  const exact = Object.values(PLATFORM_PACKS).find(
+    (pack) => pack.platform === platform && pack.version === version,
+  )
+
+  return exact ?? PLATFORM_PACKS['web-default']
+}

package/src/tokens/index.css

@@ -0,0 +1,6 @@
+/* Immutable platform packs. */
+@import './macos-27/index.css';
+@import './macos-26/index.css';
+
+/* Stable Moldable semantic and brand layer. */
+@import './moldable/index.css';

package/src/tokens/index.ts

@@ -0,0 +1,23 @@
+export {
+  CONTROL_SIZES,
+  MATERIAL_THICKNESSES,
+  PLATFORM_PACKS,
+  SIDEBAR_STYLES,
+  resolvePlatformPack,
+  type ContrastPreference,
+  type ControlSize,
+  type LayoutDensity,
+  type MaterialContext,
+  type MaterialThickness,
+  type MotionPreference,
+  type PlatformPackId,
+  type ResolvedUIAppearance,
+  type TransparencyPreference,
+  type UIAppearance,
+  type UIPlatform,
+  type UIPlatformPack,
+  type UIPlatformVersion,
+  type UIPreferences,
+  type UISidebarStyle,
+  type UITheme,
+} from './contracts'

package/src/tokens/macos-26/README.md

@@ -0,0 +1,37 @@
+# macOS 26 source pack
+
+This versioned source is separate from macOS 27 and does not correct or mutate
+that pack. The initial coverage is the inset floating sidebar used by
+Moldable.
+
+## Source
+
+- Source: macOS 26.
+- Values only.
+- No source artwork, symbols, vectors, image assets, or font files.
+
+## Composition
+
+Applications continue to select a base platform pack normally. A component
+recipe can be selected independently:
+
+```tsx
+<ThemeProvider
+  platform="macos"
+  platformVersion="27"
+  uiTheme="moldable"
+  sidebarStyle="floating"
+/>
+```
+
+This resolves the general UI from macOS 27 while resolving only the sidebar
+geometry and effects from the immutable macOS 26 source.
+
+Use `sidebarStyle="edge-to-edge"` for the macOS 27 anatomy, or
+`sidebarStyle="platform"` to follow the selected base pack.
+
+## Adaptations
+
+Intentional web divergences use stable `M26-WEB-{AREA}-{NNN}` identifiers and
+are documented in `web-adaptations.json` and `web-adaptations.md`. Source files
+remain unchanged.

package/src/tokens/macos-26/aliases.css

@@ -0,0 +1,53 @@
+/*
+ * Stable component adapter for the macOS 26 floating sidebar.
+ *
+ * This selector is intentionally independent from the base platform/version
+ * selector so Moldable can use a macOS 27 base pack with macOS 26 sidebar
+ * anatomy.
+ */
+[data-ui-platform='macos'][data-ui-platform-version='26'],
+[data-ui-sidebar-style='floating'] {
+  --m-ui-sidebar-width: var(--m26-source-sidebar-width-reference);
+  --m-ui-sidebar-window-inset: var(--m26-source-sidebar-window-inset);
+  --m-ui-sidebar-shell-radius: var(--m26-source-sidebar-radius-shell);
+  --m-ui-sidebar-item-radius: var(--m26-source-sidebar-radius-item);
+  --m-ui-sidebar-selection-radius: var(--m26-source-sidebar-radius-selection);
+  --m-ui-sidebar-corner-smoothing: var(--m26-source-sidebar-corner-smoothing);
+  --m-ui-sidebar-border-width: var(--m26-source-sidebar-border-width);
+  --m-ui-sidebar-divider-width: 0px;
+  --m-ui-sidebar-divider-color: transparent;
+  --m-ui-sidebar-shadow: var(--m26-source-sidebar-shadow);
+  --m-ui-sidebar-glass-effect-radius: var(
+    --m26-source-sidebar-glass-effect-radius
+  );
+  --m-ui-sidebar-padding-block: var(--m26-source-sidebar-padding-block);
+  --m-ui-sidebar-row-inset-inline: var(--m26-source-sidebar-row-inset-inline);
+  --m-ui-sidebar-row-height-small: var(--m26-source-sidebar-row-height-small);
+  --m-ui-sidebar-row-height-medium: var(--m26-source-sidebar-row-height-medium);
+  --m-ui-sidebar-row-height-large: var(--m26-source-sidebar-row-height-large);
+  --m-ui-sidebar-section-height-small: var(
+    --m26-source-sidebar-section-height-small
+  );
+  --m-ui-sidebar-section-height-medium: var(
+    --m26-source-sidebar-section-height-medium
+  );
+  --m-ui-sidebar-section-height-large: var(
+    --m26-source-sidebar-section-height-large
+  );
+  --m-ui-sidebar-selection-fill: var(--m26-source-sidebar-selection-light);
+  --m-ui-sidebar-material-fill: var(--m-ui-material-medium-fill);
+}
+
+/*
+ * @m26-divergence M26-WEB-COLOR-001
+ * The extracted light selection uses Multiply. Browser compositing the whole
+ * row with mix-blend-mode also blends its text and icons, so dark appearance
+ * uses a semantic alpha fill derived from the resolved platform text color.
+ */
+[data-ui-sidebar-style='floating'][data-ui-appearance='dark'] {
+  --m-ui-sidebar-selection-fill: color-mix(
+    in srgb,
+    var(--m-ui-color-text-primary) 10%,
+    transparent
+  );
+}

package/src/tokens/macos-26/compatibility.css

@@ -0,0 +1,7 @@
+[data-ui-platform='macos'][data-ui-platform-version='26'],
+[data-ui-sidebar-style='floating'] {
+  --sidebar: var(--m-ui-sidebar-material-fill);
+  --sidebar-accent: var(--m-ui-sidebar-selection-fill);
+  --density-row-height: var(--m-ui-sidebar-row-height-medium);
+  --material-shadow-sidebar: var(--m-ui-sidebar-shadow);
+}

package/src/tokens/macos-26/index.css

@@ -0,0 +1,3 @@
+@import './source/sidebar.generated.css';
+@import './aliases.css';
+@import './compatibility.css';

package/src/tokens/macos-26/source/provenance.generated.json

@@ -0,0 +1,28 @@
+{
+  "source": "macOS 26",
+  "schemaVersion": 1,
+  "scope": {
+    "platform": "macos",
+    "platformVersion": "26",
+    "publicTheme": false,
+    "immutableSourcePack": true
+  },
+  "coverage": ["floating-sidebar"],
+  "inventory": {
+    "variables": {
+      "total": 19,
+      "byType": {
+        "COLOR": 1,
+        "DIMENSION": 15,
+        "EFFECT": 1,
+        "PERCENT": 1,
+        "STRING": 1
+      }
+    }
+  },
+  "notes": [
+    "This initial source module covers the macOS 26 floating sidebar only.",
+    "It can be selected independently from the application's base platform pack.",
+    "No source artwork, symbols, vectors, image assets, or font files are included."
+  ]
+}

package/src/tokens/macos-26/source/sidebar.generated.css

@@ -0,0 +1,29 @@
+/*
+ * Generated from the macOS 26 sidebar source specification.
+ * Values only. No source artwork, symbols, vectors, or image assets.
+ *
+ * The second selector exposes this immutable source to applications that
+ * deliberately compose the macOS 26 sidebar with another base platform pack.
+ */
+[data-ui-platform='macos'][data-ui-platform-version='26'],
+[data-ui-sidebar-style='floating'] {
+  --m26-source-sidebar-width-reference: 240px;
+  --m26-source-sidebar-window-inset: 8px;
+  --m26-source-sidebar-radius-shell: 18px;
+  --m26-source-sidebar-radius-item: 5px;
+  --m26-source-sidebar-radius-selection: 8px;
+  --m26-source-sidebar-corner-smoothing: 60%;
+  --m26-source-sidebar-shadow: 0 8px 40px rgb(0 0 0 / 12%);
+  --m26-source-sidebar-glass-effect-radius: 12px;
+  --m26-source-sidebar-border-width: 0px;
+  --m26-source-sidebar-padding-block: 10px;
+  --m26-source-sidebar-row-inset-inline: 10px;
+  --m26-source-sidebar-row-height-small: 24px;
+  --m26-source-sidebar-row-height-medium: 32px;
+  --m26-source-sidebar-row-height-large: 40px;
+  --m26-source-sidebar-section-height-small: 34px;
+  --m26-source-sidebar-section-height-medium: 39px;
+  --m26-source-sidebar-section-height-large: 43px;
+  --m26-source-sidebar-selection-light: rgb(0 0 0 / 11%);
+  --m26-source-sidebar-selection-blend-mode: multiply;
+}

package/src/tokens/macos-26/source.css

@@ -0,0 +1,7 @@
+/*
+ * Immutable macOS 26 source specification.
+ *
+ * This initial entry point contains the floating-sidebar source module only.
+ * It intentionally excludes Moldable aliases and web compatibility mappings.
+ */
+@import './source/sidebar.generated.css';

package/src/tokens/macos-26/web-adaptations.json

@@ -0,0 +1,25 @@
+{
+  "source": "macOS 26",
+  "target": "web",
+  "schemaVersion": 1,
+  "idConvention": "M26-WEB-{AREA}-{NNN}",
+  "adaptations": [
+    {
+      "id": "M26-WEB-COLOR-001",
+      "area": "color",
+      "status": "intentional-divergence",
+      "summary": "Use a semantic alpha selection fill in dark appearance.",
+      "reason": "The extracted light selection uses Multiply. Applying mix-blend-mode to a browser row would also blend its text and icons, and a dark source selection value has not yet been added to this partial source module.",
+      "sourceBehavior": "An 11% black selection fill composited with Multiply in light appearance.",
+      "webBehavior": "The source fill remains exact in light appearance; dark appearance derives a 10% alpha fill from the resolved platform text color.",
+      "overrides": [
+        {
+          "appearance": "dark",
+          "token": "--m-ui-sidebar-selection-fill",
+          "sourceValue": "not-present-in-partial-source",
+          "adaptedValue": "color-mix(in srgb, var(--m-ui-color-text-primary) 10%, transparent)"
+        }
+      ]
+    }
+  ]
+}

package/src/tokens/macos-26/web-adaptations.md

@@ -0,0 +1,15 @@
+# macOS 26 web adaptations
+
+The immutable macOS 26 values live in `source/`. Effective browser behavior is
+kept in the adapter layer and identified with stable `M26-WEB-*` IDs.
+
+## M26-WEB-COLOR-001
+
+The currently extracted sidebar selection is the light-appearance value:
+11% black composited with Multiply. Applying `mix-blend-mode` to the entire
+browser row also blends its label and icon, so the light value remains exact
+while dark appearance uses a semantic 10% alpha fill derived from the resolved
+platform text color.
+
+When a dark macOS 26 source selection is added, this adaptation should be
+re-evaluated rather than silently replacing the source.

package/src/tokens/macos-27/accessibility.css

@@ -0,0 +1,11 @@
+@media (prefers-reduced-transparency: reduce) {
+  :root {
+    --m-ui-material-blur: 0px;
+  }
+}
+
+@media (prefers-contrast: more) {
+  :root {
+    --m-ui-color-text-secondary: var(--m-ui-color-text-primary);
+  }
+}