@ds-mo/ui 14.12.0 → 14.14.0

package/dist/mcp-data/registry/paper-texture.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "paper-texture",
+  "title": "PaperTexture",
+  "description": "A decorative Paper Design WebGL2 paper texture surface with Storybook-tunable literal shader parameters and a static default frame.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/paper-texture",
+    "source": "src/wc/components/PaperTexture/PaperTexture.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "specialized",
+      "status": "experimental",
+      "summary": "A decorative Paper Design WebGL2 paper texture surface with Storybook-tunable literal shader parameters and a static default frame.",
+      "useWhen": [
+        "A shell or other visual surface needs a paper or cardboard texture layered above an existing background.",
+        "Designers need to tune paper texture parameters interactively before choosing a baked static asset."
+      ],
+      "avoidWhen": [
+        "The surface needs semantic content, interaction, or accessible information.",
+        "The target environment cannot provide WebGL2 and no pre-baked fallback asset is available.",
+        "A token-driven color treatment is required; this component accepts literal shader colors only."
+      ],
+      "alternatives": [],
+      "commonlyComposedWith": [
+        "component:ds-shell-app"
+      ],
+      "accessibility": [
+        "The texture is decorative and is hidden from assistive technology.",
+        "Keep all meaningful content in the owning surface above or beside the texture."
+      ],
+      "states": [
+        "The default speed is zero, so a texture renders one deterministic frame without a recurring animation loop.",
+        "Paper shader colors are literal CSS color strings and are not resolved from TokoMo tokens.",
+        "If WebGL2 or the noise texture is unavailable, the decorative layer removes itself without blocking the owning surface."
+      ],
+      "responsiveBehavior": [
+        "The shader observes its host dimensions and follows the owning surface through resize changes.",
+        "minPixelRatio and maxPixelCount are available for explicit quality/performance tuning."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Assign config as a JavaScript property; nested shader values are not intended for serialized HTML attributes."
+        ],
+        "react": [
+          "Use the generated wrapper and pass the config object as a property."
+        ],
+        "angular": [
+          "Bind the config object as a property so nested shader values are preserved."
+        ]
+      },
+      "references": [
+        {
+          "label": "Storybook parameter playground",
+          "path": "src/wc/components/PaperTexture/PaperTexture.stories.ts"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "config": {
+          "type": "PaperTextureConfig",
+          "resolvedType": "PaperTextureConfig",
+          "default": "{}",
+          "required": false,
+          "mutable": false,
+          "description": "Paper Design shader parameters. Set as a JavaScript property."
+        }
+      },
+      "events": [],
+      "methods": [],
+      "slots": []
+    },
+    "props": {
+      "config": {
+        "type": "PaperTextureConfig",
+        "resolvedType": "PaperTextureConfig",
+        "default": "{}",
+        "required": false,
+        "mutable": false,
+        "description": "Paper Design shader parameters. Set as a JavaScript property."
+      }
+    },
+    "events": [],
+    "methods": [],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-paper-texture",
+      "react": "DsPaperTexture",
+      "angular": "DsPaperTexture"
+    },
+    "consumption": {
+      "install": "npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons",
+      "cssSetup": "import '@ds-mo/tokens';\nimport '@ds-mo/tokens/reset';\nimport '@ds-mo/tokens/globals';",
+      "customElements": {
+        "import": "import '@ds-mo/ui/dist/components/ds-paper-texture.js';",
+        "example": "<ds-paper-texture></ds-paper-texture>"
+      },
+      "react": {
+        "import": "import { DsPaperTexture } from '@ds-mo/ui/react';",
+        "example": "<DsPaperTexture />"
+      },
+      "angular": {
+        "import": "import { DsPaperTexture } from '@ds-mo/ui/angular/ds-paper-texture';",
+        "example": "<ds-paper-texture></ds-paper-texture>"
+      },
+      "complexPropertyNote": "Assign these non-primitive values as JavaScript properties: config.",
+      "peerDependencies": {
+        "required": [
+          "@ds-mo/tokens ^6.5.0",
+          "@ds-mo/icons ^7.0.0"
+        ],
+        "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
+      }
+    }
+  },
+  "dependencies": [
+    "@ds-mo/ui",
+    "@ds-mo/tokens"
+  ],
+  "registryDependencies": [],
+  "files": [
+    {
+      "path": "src/wc/components/PaperTexture/PaperTexture.css",
+      "content": ":host {\n  position: absolute;\n  inset: 0;\n  display: block;\n  overflow: hidden;\n  pointer-events: none;\n  opacity: var(--ds-paper-texture-opacity, 1);\n}\n\n.paper-texture__mount {\n  position: absolute;\n  inset: 0;\n  width: 100%;\n  height: 100%;\n  overflow: hidden;\n  isolation: isolate;\n}\n\n.paper-texture__mount[data-paper-shader] canvas {\n  z-index: 0;\n}\n\n:host([data-paper-texture-error]) {\n  display: none;\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/PaperTexture/PaperTexture.tsx",
+      "content": "import { Component, Element, Host, Prop, Watch, h } from '@stencil/core';\nimport {\n  emptyPixel,\n  getShaderColorFromString,\n  getShaderNoiseTexture,\n  paperTextureFragmentShader,\n  ShaderFitOptions,\n  ShaderMount,\n  type ShaderMountUniforms,\n} from '@paper-design/shaders';\nimport { DEFAULT_PAPER_TEXTURE_CONFIG, type PaperTextureConfig } from './paper-texture-types';\n\nlet emptyPixelPromise: Promise<HTMLImageElement> | undefined;\nlet noiseTexturePromise: Promise<HTMLImageElement> | undefined;\n\nfunction waitForImage(image: HTMLImageElement): Promise<HTMLImageElement> {\n  if (image.complete) {\n    return image.naturalWidth > 0\n      ? Promise.resolve(image)\n      : Promise.reject(new Error(`Paper texture image failed to load: ${image.src}`));\n  }\n\n  return new Promise((resolve, reject) => {\n    const onLoad = () => {\n      cleanup();\n      resolve(image);\n    };\n    const onError = () => {\n      cleanup();\n      reject(new Error(`Paper texture image failed to load: ${image.src}`));\n    };\n    const cleanup = () => {\n      image.removeEventListener('load', onLoad);\n      image.removeEventListener('error', onError);\n    };\n\n    image.addEventListener('load', onLoad, { once: true });\n    image.addEventListener('error', onError, { once: true });\n  });\n}\n\nfunction loadImage(source: HTMLImageElement | string | undefined): Promise<HTMLImageElement> {\n  if (source instanceof HTMLImageElement) return waitForImage(source);\n\n  const image = new Image();\n  if (source && source !== emptyPixel) image.crossOrigin = 'anonymous';\n  image.src = source || emptyPixel;\n  return waitForImage(image);\n}\n\nfunction loadEmptyPixel(): Promise<HTMLImageElement> {\n  emptyPixelPromise ??= loadImage(emptyPixel);\n  return emptyPixelPromise;\n}\n\nfunction loadNoiseTexture(): Promise<HTMLImageElement> {\n  noiseTexturePromise ??= Promise.resolve(getShaderNoiseTexture()).then(image => {\n    if (!image) throw new Error('Paper texture noise texture is unavailable');\n    return waitForImage(image);\n  });\n  return noiseTexturePromise;\n}\n\n@Component({\n  tag: 'ds-paper-texture',\n  styleUrl: 'PaperTexture.css',\n  scoped: true,\n})\nexport class PaperTexture {\n  @Element() el!: HTMLElement;\n\n  /** Paper Design shader parameters. Set as a JavaScript property. */\n  @Prop() config: PaperTextureConfig = {};\n\n  private shaderMount?: ShaderMount;\n  private syncGeneration = 0;\n  private hasLoaded = false;\n\n  componentDidLoad() {\n    this.hasLoaded = true;\n    void this.syncShader();\n  }\n\n  connectedCallback() {\n    if (this.hasLoaded) void this.syncShader();\n  }\n\n  disconnectedCallback() {\n    this.syncGeneration += 1;\n    this.disposeShader();\n  }\n\n  @Watch('config')\n  onConfigChange() {\n    if (this.hasLoaded) void this.syncShader();\n  }\n\n  private resolvedConfig(): Required<Omit<PaperTextureConfig, 'image'>> &\n    Pick<PaperTextureConfig, 'image'> {\n    return {\n      ...DEFAULT_PAPER_TEXTURE_CONFIG,\n      ...(this.config ?? {}),\n    };\n  }\n\n  private async syncShader() {\n    const generation = ++this.syncGeneration;\n    const config = this.resolvedConfig();\n\n    try {\n      const [image, noiseTexture] = await Promise.all([\n        loadImage(config.image).catch(() => loadEmptyPixel()),\n        loadNoiseTexture(),\n      ]);\n\n      if (generation !== this.syncGeneration || !this.el.isConnected) return;\n\n      const uniforms = this.buildUniforms(config, image, noiseTexture);\n      const mountElement = this.el.querySelector<HTMLElement>('.paper-texture__mount');\n      if (!mountElement) return;\n\n      if (!this.shaderMount) {\n        this.shaderMount = new ShaderMount(\n          mountElement,\n          paperTextureFragmentShader,\n          uniforms,\n          undefined,\n          config.speed,\n          config.frame,\n          config.minPixelRatio,\n          config.maxPixelCount,\n          ['u_image']\n        );\n      } else {\n        this.shaderMount.setUniforms(uniforms);\n        this.shaderMount.setSpeed(config.speed);\n        this.shaderMount.setFrame(config.frame);\n        this.shaderMount.setMinPixelRatio(config.minPixelRatio);\n        this.shaderMount.setMaxPixelCount(config.maxPixelCount);\n      }\n\n      this.el.removeAttribute('data-paper-texture-error');\n    } catch (error) {\n      if (generation !== this.syncGeneration) return;\n      this.disposeShader();\n      this.el.querySelector<HTMLElement>('.paper-texture__mount')?.replaceChildren();\n      this.el.setAttribute('data-paper-texture-error', 'unavailable');\n      console.warn('[ds-paper-texture] WebGL2 paper texture unavailable.', error);\n    }\n  }\n\n  private buildUniforms(\n    config: Required<Omit<PaperTextureConfig, 'image'>> & Pick<PaperTextureConfig, 'image'>,\n    image: HTMLImageElement,\n    noiseTexture: HTMLImageElement\n  ): ShaderMountUniforms {\n    return {\n      u_image: image,\n      u_noiseTexture: noiseTexture,\n      u_colorFront: getShaderColorFromString(config.colorFront),\n      u_colorBack: getShaderColorFromString(config.colorBack),\n      u_contrast: config.contrast,\n      u_roughness: config.roughness,\n      u_fiber: config.fiber,\n      u_fiberSize: config.fiberSize,\n      u_crumples: config.crumples,\n      u_crumpleSize: config.crumpleSize,\n      u_foldCount: config.foldCount,\n      u_folds: config.folds,\n      u_fade: config.fade,\n      u_drops: config.drops,\n      u_seed: config.seed,\n      u_fit: ShaderFitOptions[config.fit],\n      u_scale: config.scale,\n      u_rotation: config.rotation,\n      u_offsetX: config.offsetX,\n      u_offsetY: config.offsetY,\n      u_originX: config.originX,\n      u_originY: config.originY,\n      u_worldWidth: config.worldWidth,\n      u_worldHeight: config.worldHeight,\n    };\n  }\n\n  private disposeShader() {\n    this.shaderMount?.dispose();\n    this.shaderMount = undefined;\n  }\n\n  render() {\n    const config = this.resolvedConfig();\n    return (\n      <Host aria-hidden=\"true\" style={{ '--ds-paper-texture-opacity': String(config.opacity) }}>\n        <div class=\"paper-texture__mount\" />\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/PaperTexture/paper-texture-types.ts",
+      "content": "export type PaperTextureFit = 'none' | 'contain' | 'cover';\n\n/**\n * Literal parameters forwarded to Paper Design's paper texture shader.\n * Colors intentionally remain ordinary CSS color strings; they are not token\n * references and are parsed once into shader RGBA uniforms.\n */\nexport interface PaperTextureConfig {\n  image?: HTMLImageElement | string;\n  colorFront?: string;\n  colorBack?: string;\n  contrast?: number;\n  roughness?: number;\n  fiber?: number;\n  fiberSize?: number;\n  crumples?: number;\n  crumpleSize?: number;\n  folds?: number;\n  foldCount?: number;\n  fade?: number;\n  drops?: number;\n  seed?: number;\n  fit?: PaperTextureFit;\n  scale?: number;\n  rotation?: number;\n  originX?: number;\n  originY?: number;\n  offsetX?: number;\n  offsetY?: number;\n  worldWidth?: number;\n  worldHeight?: number;\n  speed?: number;\n  frame?: number;\n  minPixelRatio?: number;\n  maxPixelCount?: number;\n  /** CSS opacity applied after the shader has rendered. */\n  opacity?: number;\n}\n\nexport const DEFAULT_PAPER_TEXTURE_CONFIG: Required<Omit<PaperTextureConfig, 'image'>> = {\n  colorFront: '#b8b8b8',\n  colorBack: '#ffffff',\n  contrast: 0.3,\n  roughness: 0.4,\n  fiber: 0.3,\n  fiberSize: 0.2,\n  crumples: 0.3,\n  crumpleSize: 0.35,\n  folds: 0.65,\n  foldCount: 5,\n  fade: 0,\n  drops: 0.2,\n  seed: 5.8,\n  fit: 'cover',\n  scale: 0.6,\n  rotation: 0,\n  originX: 0.5,\n  originY: 0.5,\n  offsetX: 0,\n  offsetY: 0,\n  worldWidth: 0,\n  worldHeight: 0,\n  speed: 0,\n  frame: 0,\n  minPixelRatio: 2,\n  maxPixelCount: 1920 * 1080 * 4,\n  opacity: 1,\n};\n",
+      "type": "registry:ui"
+    }
+  ]
+}

package/dist/mcp-data/registry/registry.json

@@ -4197,7 +4197,7 @@
     {
       "name": "input",
       "title": "Input",
-      "description": "Form-associated single-line text field for primary and secondary application backgrounds, with native text input behavior, four control densities, optional leading and trailing content, search clearing, and validation.",
+      "description": "Form-associated single-line text and number field for primary and secondary application backgrounds, with native input behavior, four control densities, optional leading and trailing content, search clearing, and validation.",
       "type": "registry:ui",
       "meta": {
         "library": "@ds-mo/ui",
@@ -4208,9 +4208,9 @@
         "intent": {
           "audience": "general",
           "status": "stable",
-          "summary": "Form-associated single-line text field for primary and secondary application backgrounds, with native text input behavior, four control densities, optional leading and trailing content, search clearing, and validation.",
+          "summary": "Form-associated single-line text and number field for primary and secondary application backgrounds, with native input behavior, four control densities, optional leading and trailing content, search clearing, and validation.",
           "useWhen": [
-            "A user must enter or edit one line of text, an email address, telephone number, URL, search query, or password.",
+            "A user must enter or edit one line of text, an email address, telephone number, URL, search query, password, or exact number.",
             "The value must participate in native, Angular, or React form state.",
             "A compact filter or toolbar needs a single-line search field that follows the shared control-density recipe."
           ],
@@ -4256,6 +4256,7 @@
             "Search fields show a standard borderless CrossCircle icon action only while they contain a value. Clearing emits the empty value and restores focus to the native field.",
             "The suffix slot is for compact units or decorations. The optional leading icon is decorative and does not replace the field label.",
             "Use autoComplete, inputMode, and enterKeyHint to provide browser and virtual-keyboard hints without changing the value's semantic type.",
+            "Number fields preserve native spinbutton semantics, stepping, and min/max constraint behavior while dsChange continues to report the native string value.",
             "The host exposes focused, filled, dirty, touched, invalid, disabled, read-only, and required data attributes for Field integration and diagnostics.",
             "Use Input only on primary or secondary application backgrounds. It intentionally does not expose alternate surface contexts."
           ],
@@ -4352,6 +4353,14 @@
             "type": "boolean",
             "required": false
           },
+          "max": {
+            "type": "number | undefined",
+            "required": false
+          },
+          "min": {
+            "type": "number | undefined",
+            "required": false
+          },
           "name": {
             "type": "string | undefined",
             "required": false
@@ -4376,6 +4385,10 @@
             "type": "InputSize",
             "required": false
           },
+          "step": {
+            "type": "number | undefined",
+            "required": false
+          },
           "type": {
             "type": "InputType",
             "required": false
@@ -6928,6 +6941,85 @@
         "tooltip"
       ]
     },
+    {
+      "name": "paper-texture",
+      "title": "PaperTexture",
+      "description": "A decorative Paper Design WebGL2 paper texture surface with Storybook-tunable literal shader parameters and a static default frame.",
+      "type": "registry:ui",
+      "meta": {
+        "library": "@ds-mo/ui",
+        "distribution": "npm",
+        "storybook": "https://zainadeel.github.io/compomo/?path=/story/paper-texture",
+        "source": "src/wc/components/PaperTexture/PaperTexture.tsx",
+        "intentStatus": "complete",
+        "intent": {
+          "audience": "specialized",
+          "status": "experimental",
+          "summary": "A decorative Paper Design WebGL2 paper texture surface with Storybook-tunable literal shader parameters and a static default frame.",
+          "useWhen": [
+            "A shell or other visual surface needs a paper or cardboard texture layered above an existing background.",
+            "Designers need to tune paper texture parameters interactively before choosing a baked static asset."
+          ],
+          "avoidWhen": [
+            "The surface needs semantic content, interaction, or accessible information.",
+            "The target environment cannot provide WebGL2 and no pre-baked fallback asset is available.",
+            "A token-driven color treatment is required; this component accepts literal shader colors only."
+          ],
+          "alternatives": [],
+          "commonlyComposedWith": [
+            "component:ds-shell-app"
+          ],
+          "accessibility": [
+            "The texture is decorative and is hidden from assistive technology.",
+            "Keep all meaningful content in the owning surface above or beside the texture."
+          ],
+          "states": [
+            "The default speed is zero, so a texture renders one deterministic frame without a recurring animation loop.",
+            "Paper shader colors are literal CSS color strings and are not resolved from TokoMo tokens.",
+            "If WebGL2 or the noise texture is unavailable, the decorative layer removes itself without blocking the owning surface."
+          ],
+          "responsiveBehavior": [
+            "The shader observes its host dimensions and follows the owning surface through resize changes.",
+            "minPixelRatio and maxPixelCount are available for explicit quality/performance tuning."
+          ],
+          "frameworkCaveats": {
+            "customElements": [
+              "Assign config as a JavaScript property; nested shader values are not intended for serialized HTML attributes."
+            ],
+            "react": [
+              "Use the generated wrapper and pass the config object as a property."
+            ],
+            "angular": [
+              "Bind the config object as a property so nested shader values are preserved."
+            ]
+          },
+          "references": [
+            {
+              "label": "Storybook parameter playground",
+              "path": "src/wc/components/PaperTexture/PaperTexture.stories.ts"
+            }
+          ]
+        },
+        "props": {
+          "config": {
+            "type": "PaperTextureConfig",
+            "required": false
+          }
+        },
+        "events": [],
+        "slots": [],
+        "exports": {
+          "customElement": "ds-paper-texture",
+          "react": "DsPaperTexture",
+          "angular": "DsPaperTexture"
+        }
+      },
+      "dependencies": [
+        "@ds-mo/ui",
+        "@ds-mo/tokens"
+      ],
+      "registryDependencies": []
+    },
     {
       "name": "radio",
       "title": "Radio",
@@ -7515,7 +7607,8 @@
             "component:ds-mobile-bar-nav",
             "component:ds-shell-page",
             "component:ds-banner",
-            "component:ds-swatch-picker"
+            "component:ds-swatch-picker",
+            "component:ds-paper-texture"
           ],
           "patterns": [
             "pattern:application-shell",
@@ -7541,6 +7634,7 @@
             "Use composition=slotted only for advanced application architectures that intentionally own all lower-level chrome wiring.",
             "Set gradientPreset to the single resolved global chrome preference: neutral by default, none for solid chrome, or cool, neutral, warm, and fresh for token-based washes.",
             "The application owns gradient preference persistence, cross-tab synchronization, and server or account precedence; ShellApp owns rendering the resolved preset across authenticated routes.",
+            "The optional paperTexture property adds a decorative Paper Design texture layer above the gradient or solid chrome frame; its color values are literal shader inputs rather than design tokens.",
             "Dashboard represents day-to-day operational work while Settings represents administrative and configuration work; route state selects the context.",
             "Replace navigation and pageChrome together from one completed route state.",
             "When pageChrome.showBack marks a detail depth, mobile chrome keeps the page heading as its identity and presents only local subsections; peer route tabs remain in desktop BarNav rather than replacing the detail heading.",
@@ -7561,20 +7655,24 @@
             "A slotted Banner remains below the top safe-area inset and above routed, navigation, fullscreen-tool, and mobile global-surface presentations.",
             "Mobile global surfaces conceal and inert the routed workspace without unmounting it, preserving nested routes and scroll state.",
             "Keep PanelNav width, BarNav height, PanelTools chrome, and main-content origin stable except during intentional responsive or collapse transitions.",
+            "Paper texture chrome is desktop/tablet-only and follows the fixed viewport phase of the shell chrome; mobile remains a solid primary stage.",
             "Managed page-header capacity follows only the fixed shell breakpoint: roomy on desktop and compact on tablet. Opening PanelTools does not compact or constrain BarTitle.",
             "The bottom bar remains visible at all route and tool depths in the foundation release."
           ],
           "frameworkCaveats": {
             "customElements": [
               "Assign navigation, pageChrome, and tools as JavaScript properties on the managed ShellApp.",
+              "Assign paperTexture as a JavaScript property when enabling the optional decorative layer.",
               "Stamp route-derived nav-style before components connect when deterministic first paint is required."
             ],
             "react": [
               "Use the generated ShellApp wrapper, structured object props, named tool-view slots, and stable routed children.",
+              "Pass paperTexture as a structured property when the shell needs the optional texture layer.",
               "Resolve all shell inputs from one router state before rendering the composition."
             ],
             "angular": [
               "Use the generated standalone ShellApp adapter, bind structured object props, and preserve named tool-view slots.",
+              "Bind paperTexture as a property so nested shader parameters are preserved.",
               "Bind complex inputs as properties and update navigation inputs atomically from one resolved router state.",
               "Bind both nav-style attributes and properties when deterministic first paint is required."
             ]
@@ -7627,6 +7725,10 @@
             "type": "ShellPageChromeConfig",
             "required": false
           },
+          "paperTexture": {
+            "type": "PaperTextureConfig",
+            "required": false
+          },
           "shortcutsEnabled": {
             "type": "boolean",
             "required": false
@@ -7713,6 +7815,7 @@
         "mobile-header",
         "mobile-sheet-nav",
         "panel-nav",
+        "paper-texture",
         "shell-page",
         "shell-tools",
         "tooltip"