@ship-ui/core 0.22.12 → 0.22.15

package/assets/mcp/components.json

@@ -231,6 +231,430 @@
     ],
     "examples": []
   },
+  {
+    "name": "ShipEditor",
+    "selector": "sh-editor",
+    "path": "core/projects/ship-ui/ship-editor/ship-editor.ts",
+    "description": "### Usage\n\nShipEditor is a premium, config-driven WYSIWYG rich text editor. It allows typing in design view, editing raw source code, and can serialize to `html`, `markdown`, or `json` configuration dynamically.\n\n### Features\n\n- Three output formats: HTML strings, Markdown text, and custom structured block/mark JSON.\n- ControlValueAccessor integration for Reactive and Template-driven forms.\n- Monospace code-view for editing source code directly.\n- Dynamic toolbar selection tracking.\n- Word and character count reporting in the status footer.",
+    "keywords": [
+      "editor",
+      "wysiwyg",
+      "richtext",
+      "html",
+      "markdown",
+      "json",
+      "input",
+      "form"
+    ],
+    "inputs": [
+      {
+        "name": "format",
+        "type": "'json' | 'html' | 'markdown'",
+        "description": "",
+        "defaultValue": "'html'"
+      },
+      {
+        "name": "placeholder",
+        "type": "string",
+        "description": "",
+        "defaultValue": "'Type your content here...'"
+      },
+      {
+        "name": "readonly",
+        "type": "boolean",
+        "description": "",
+        "defaultValue": "false"
+      },
+      {
+        "name": "toolbar",
+        "type": "boolean",
+        "description": "",
+        "defaultValue": "true"
+      },
+      {
+        "name": "color",
+        "type": "ShipColor | null",
+        "description": "",
+        "defaultValue": "null"
+      },
+      {
+        "name": "variant",
+        "type": "'base' | 'type-b' | null",
+        "description": "",
+        "defaultValue": "'base'"
+      },
+      {
+        "name": "customCommands",
+        "type": "ShipEditorCommand[]",
+        "description": "",
+        "defaultValue": "[]"
+      },
+      {
+        "name": "slashCommands",
+        "type": "boolean | string[]",
+        "description": "",
+        "defaultValue": "true"
+      },
+      {
+        "name": "showFormats",
+        "type": "boolean",
+        "description": "",
+        "defaultValue": "true"
+      },
+      {
+        "name": "showBlocks",
+        "type": "boolean",
+        "description": "",
+        "defaultValue": "true"
+      },
+      {
+        "name": "showLists",
+        "type": "boolean",
+        "description": "",
+        "defaultValue": "true"
+      },
+      {
+        "name": "showAlignments",
+        "type": "boolean",
+        "description": "",
+        "defaultValue": "true"
+      },
+      {
+        "name": "showInsertions",
+        "type": "boolean",
+        "description": "",
+        "defaultValue": "true"
+      },
+      {
+        "name": "showHistory",
+        "type": "boolean",
+        "description": "",
+        "defaultValue": "true"
+      },
+      {
+        "name": "customUpload",
+        "type": "boolean",
+        "description": "",
+        "defaultValue": "false"
+      },
+      {
+        "name": "imageUploadEnabled",
+        "type": "boolean",
+        "description": "",
+        "defaultValue": "true"
+      },
+      {
+        "name": "value",
+        "type": "string | ShipEditorDocument | null",
+        "description": "",
+        "defaultValue": "''"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "imageUpload",
+        "type": "File",
+        "description": ""
+      }
+    ],
+    "methods": [
+      {
+        "name": "execCommand",
+        "parameters": "commandId: string, showUI?: boolean, value?: string",
+        "returnType": "boolean;\n  queryCommandState(commandId: string): boolean;\n  queryCommandEnabled(commandId: string): boolean;\n}\n\n// Value Accessor Provider\nconst SHIP_EDITOR_VALUE_ACCESSOR: Provider =",
+        "description": ""
+      },
+      {
+        "name": "effect",
+        "parameters": "() => {\n      this.showFormats();\n      this.showBlocks();\n      this.showLists();\n      this.showAlignments();\n      this.showInsertions();\n      this.showHistory();\n      this.toolbar();\n      this.readonly();\n      this.#initializeToolbarTabindexes();\n    });\n  }\n\n  ngOnInit(",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "clearTimeout",
+        "parameters": "this.#typingTimeout);\n    }\n\n    if (saveImmediately",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "registerOnChange",
+        "parameters": "fn: (value: ShipEditorValue) => void",
+        "returnType": "void",
+        "description": ""
+      },
+      {
+        "name": "registerOnTouched",
+        "parameters": "fn: () => void",
+        "returnType": "void",
+        "description": ""
+      },
+      {
+        "name": "setDisabledState",
+        "parameters": "isDisabled: boolean",
+        "returnType": "void",
+        "description": ""
+      },
+      {
+        "name": "formatText",
+        "parameters": "command: string, value: string = ''",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "applyInlineStyle",
+        "parameters": "tag: string",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "while",
+        "parameters": "node",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "toggleLink",
+        "parameters": "url: string",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "setBlockType",
+        "parameters": "tag: string",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "toggleList",
+        "parameters": "listType: 'ul' | 'ol'",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "insertHorizontalRule",
+        "parameters": "",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "setAlign",
+        "parameters": "direction: 'left' | 'center' | 'right'",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "removeFormat",
+        "parameters": "",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "undo",
+        "parameters": "",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "openLinkModal",
+        "parameters": "",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "openImageModal",
+        "parameters": "",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "onComponentFocusIn",
+        "parameters": "event: FocusEvent",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "onComponentClick",
+        "parameters": "event: MouseEvent",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "onKeyDown",
+        "parameters": "event: KeyboardEvent",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "onKeyUp",
+        "parameters": "event: KeyboardEvent",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "executeCommand",
+        "parameters": "cmd: ShipEditorCommand",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "getBlockLabel",
+        "parameters": "",
+        "returnType": "string",
+        "description": ""
+      },
+      {
+        "name": "onComponentScroll",
+        "parameters": "event: Event",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "onWindowResize",
+        "parameters": "",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "updateImgToolbarPosition",
+        "parameters": "",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "onFileSelected",
+        "parameters": "event: Event",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "onDrop",
+        "parameters": "event: DragEvent",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "onPaste",
+        "parameters": "event: ClipboardEvent",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "insertImage",
+        "parameters": "url: string",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "getHTML",
+        "parameters": "",
+        "returnType": "string",
+        "description": ""
+      },
+      {
+        "name": "getMarkdown",
+        "parameters": "",
+        "returnType": "string",
+        "description": ""
+      },
+      {
+        "name": "getJSON",
+        "parameters": "",
+        "returnType": "ShipEditorDocument",
+        "description": ""
+      },
+      {
+        "name": "setHTML",
+        "parameters": "html: string",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "setMarkdown",
+        "parameters": "md: string",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "setJSON",
+        "parameters": "json: ShipEditorDocument",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "clear",
+        "parameters": "",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "traverse",
+        "parameters": "child);\n    }\n\n    return md;\n  }\n\n  // Markdown => HTML Converter\n  #markdownToHTML(markdown: string",
+        "returnType": "string",
+        "description": ""
+      }
+    ],
+    "cssVariables": [
+      {
+        "name": "--editor-bg",
+        "defaultValue": "var(--base-1)"
+      },
+      {
+        "name": "--editor-code-bg",
+        "defaultValue": "var(--base-2)"
+      },
+      {
+        "name": "--editor-border-color",
+        "defaultValue": "var(--base-4)"
+      },
+      {
+        "name": "--editor-toolbar-bg",
+        "defaultValue": "rgb(from var(--base-1) r g b / 70%)"
+      },
+      {
+        "name": "--editor-toolbar-border",
+        "defaultValue": "var(--base-4)"
+      },
+      {
+        "name": "--editor-btn-hover",
+        "defaultValue": "var(--base-3)"
+      },
+      {
+        "name": "--editor-btn-active-bg",
+        "defaultValue": "var(--primary-3)"
+      },
+      {
+        "name": "--editor-btn-active-c",
+        "defaultValue": "var(--primary-11)"
+      },
+      {
+        "name": "--editor-footer-bg",
+        "defaultValue": "var(--base-2)"
+      },
+      {
+        "name": "--editor-p",
+        "defaultValue": "#{p2r(16)} #{p2r(20)}"
+      },
+      {
+        "name": "--editor-min-h",
+        "defaultValue": "#{p2r(220)}"
+      },
+      {
+        "name": "--editor-border-focus",
+        "defaultValue": "var(--primary-8)"
+      },
+      {
+        "name": "--editor-shadow-focus",
+        "defaultValue": "0 0 0 3px var(--primary-3)"
+      }
+    ],
+    "examples": [
+      {
+        "name": "sandbox-editor",
+        "html": "<div class=\"sandbox-container\">\n  <div class=\"sandbox-sidebar\">\n    <sh-card class=\"type-b control-card\">\n      <h3>Options</h3>\n\n      <div class=\"control-group\">\n        <label class=\"control-label\">Storage Format</label>\n        <sh-button-group size=\"small\" [value]=\"selectedFormat()\" (valueChange)=\"onFormatChange($event)\">\n          <button value=\"html\">HTML</button>\n          <button value=\"markdown\">Markdown</button>\n          <button value=\"json\">JSON</button>\n        </sh-button-group>\n      </div>\n\n      <div class=\"control-group inline\">\n        <label for=\"readonly-toggle\" class=\"control-label\">Read-Only</label>\n        <sh-toggle id=\"readonly-toggle\" [(checked)]=\"isReadonly\"></sh-toggle>\n      </div>\n\n      <div class=\"control-group inline\">\n        <label for=\"toolbar-toggle\" class=\"control-label\">Show Toolbar</label>\n        <sh-toggle id=\"toolbar-toggle\" [(checked)]=\"showToolbar\"></sh-toggle>\n      </div>\n\n      <div class=\"control-group inline\">\n        <label for=\"image-upload-toggle\" class=\"control-label\">Image Upload</label>\n        <sh-toggle id=\"image-upload-toggle\" [(checked)]=\"imageUploadEnabled\"></sh-toggle>\n      </div>\n\n      @if (showToolbar()) {\n        <div class=\"control-group-section-title\">Toolbar Groups</div>\n\n        <div class=\"control-group inline\">\n          <label for=\"formats-toggle\" class=\"control-label\">Formats</label>\n          <sh-toggle id=\"formats-toggle\" [(checked)]=\"showFormats\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"blocks-toggle\" class=\"control-label\">Blocks/Headings</label>\n          <sh-toggle id=\"blocks-toggle\" [(checked)]=\"showBlocks\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"lists-toggle\" class=\"control-label\">Lists</label>\n          <sh-toggle id=\"lists-toggle\" [(checked)]=\"showLists\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"align-toggle\" class=\"control-label\">Alignments</label>\n          <sh-toggle id=\"align-toggle\" [(checked)]=\"showAlignments\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"insert-toggle\" class=\"control-label\">Insertions</label>\n          <sh-toggle id=\"insert-toggle\" [(checked)]=\"showInsertions\"></sh-toggle>\n        </div>\n\n        <div class=\"control-group inline\">\n          <label for=\"history-toggle\" class=\"control-label\">History/Code</label>\n          <sh-toggle id=\"history-toggle\" [(checked)]=\"showHistory\"></sh-toggle>\n        </div>\n      }\n    </sh-card>\n  </div>\n\n  <div class=\"sandbox-editor-wrapper\">\n    <sh-editor\n      [(value)]=\"editorValue\"\n      [format]=\"selectedFormat()\"\n      [readonly]=\"isReadonly()\"\n      [toolbar]=\"showToolbar()\"\n      [showFormats]=\"showFormats()\"\n      [showBlocks]=\"showBlocks()\"\n      [showLists]=\"showLists()\"\n      [showAlignments]=\"showAlignments()\"\n      [showInsertions]=\"showInsertions()\"\n      [showHistory]=\"showHistory()\"\n      [customCommands]=\"customEditorCommands()\"\n      [imageUploadEnabled]=\"imageUploadEnabled()\"\n      placeholder=\"Start writing your premium content here...\">\n      <!-- Projected custom toolbar action -->\n      <button type=\"button\" class=\"sh-editor-btn\" (click)=\"customAction()\" shTooltip=\"Projected Action (Star)\">\n        <sh-icon>star</sh-icon>\n      </button>\n    </sh-editor>\n\n    <sh-card class=\"type-b output-card\">\n      <div class=\"output-header\">\n        <h3>Database Output</h3>\n        <button shButton variant=\"outlined\" size=\"small\" (click)=\"copyToClipboard()\">\n          <sh-icon>copy</sh-icon>\n          Copy\n        </button>\n      </div>\n      <p class=\"output-desc\">This is exactly what would be saved in your database:</p>\n      <pre class=\"serialized-preview\"><code>{{ serializedOutput() }}</code></pre>\n    </sh-card>\n  </div>\n</div>\n",
+        "ts": "import { ChangeDetectionStrategy, Component, computed, signal, viewChild } from '@angular/core';\nimport { ShipColor } from '@ship-ui/core';\nimport { ShipButton } from '@ship-ui/core/ship-button';\nimport { ShipButtonGroup } from '@ship-ui/core/ship-button-group';\nimport { ShipCard } from '@ship-ui/core/ship-card';\nimport { ShipEditor, ShipEditorCommand, ShipEditorValue } from '@ship-ui/core/ship-editor';\nimport { ShipIcon } from '@ship-ui/core/ship-icon';\nimport { ShipToggle } from '@ship-ui/core/ship-toggle';\n\n@Component({\n  selector: 'app-sandbox-editor',\n  standalone: true,\n  imports: [ShipEditor, ShipButton, ShipCard, ShipToggle, ShipIcon, ShipButtonGroup],\n  templateUrl: './sandbox-editor.html',\n  styleUrl: './sandbox-editor.scss',\n  changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class SandboxEditor {\n  // Current format selection\n  selectedFormat = signal<'html' | 'markdown' | 'json'>('html');\n\n  editor = viewChild(ShipEditor);\n\n  // Editor states\n  isReadonly = signal<boolean>(false);\n  showToolbar = signal<boolean>(true);\n  selectedColor = signal<ShipColor | null>(null);\n  imageUploadEnabled = signal<boolean>(true);\n\n  // Toolbar group configurations\n  showFormats = signal<boolean>(true);\n  showBlocks = signal<boolean>(true);\n  showLists = signal<boolean>(true);\n  showAlignments = signal<boolean>(true);\n  showInsertions = signal<boolean>(true);\n  showHistory = signal<boolean>(true);\n\n  // Custom action for projected button\n  customAction() {\n    alert('Custom Projected Button Clicked!');\n  }\n\n  customEditorCommands = signal<ShipEditorCommand[]>([\n    {\n      id: 'highlight',\n      label: 'Highlight Text',\n      icon: 'star',\n      description: 'Highlight selected text in yellow',\n      action: (editor) => {\n        editor.formatText('backColor', '#fff2b2');\n      },\n    },\n    {\n      id: 'info-callout',\n      label: 'Info Callout',\n      icon: 'terminal',\n      description: 'Insert an info callout box',\n      action: (editor) => {\n        editor.formatText(\n          'insertHTML',\n          '<div style=\"background-color: var(--primary-2); border-left: 4px solid var(--primary-9); padding: 12px 16px; margin: 12px 0; border-radius: 4px; color: var(--base-12);\"><strong>Info:</strong> Start typing callout contents here...</div>'\n        );\n      },\n    },\n  ]);\n\n  // Pre-populated initial contents for each format\n  initialHtml = `<h1>Ship WYSIWYG Editor</h1><p>Welcome! This is a <strong>config-driven</strong> rich-text editor designed to support flexible storage formats.</p><ul><li><strong>Two-way binding</strong> with <code>ControlValueAccessor</code></li><li>Instant conversion to <strong>HTML</strong>, <strong>Markdown</strong>, or <strong>JSON</strong></li><li>Sticky blur-toolbar, light/dark mode support, and word counting</li></ul><blockquote>\"A beautiful interface makes editing content a delight.\"</blockquote><hr><p>Try changing the storage format below to see the serialized output update in real time!</p>`;\n\n  // Current value model\n  editorValue = signal<ShipEditorValue>(this.initialHtml);\n\n  // Stringified preview for database presentation\n  serializedOutput = computed(() => {\n    const val = this.editorValue();\n    if (val === null || val === undefined) return '';\n    if (typeof val === 'string') return val;\n    return JSON.stringify(val, null, 2);\n  });\n\n  // Handle format swapping, converting the value appropriately\n  onFormatChange(format: string | null) {\n    if (format === 'html' || format === 'markdown' || format === 'json') {\n      this.selectedFormat.set(format);\n    }\n  }\n\n  // Copy serialized contents to clipboard\n  copyToClipboard() {\n    navigator.clipboard.writeText(this.serializedOutput());\n  }\n}\n"
+      }
+    ]
+  },
   {
     "name": "ShipBlueprint",
     "selector": "sh-blueprint",
@@ -1532,8 +1956,20 @@
       },
       {
         "name": "cancelAnimationFrame",
-        "parameters": "this.#animationFrameRequest);\n    }\n  }\n}\n\n@Directive({\n  selector: '[shSort]',\n  standalone: true,\n  host: {\n    'role': 'columnheader',\n    '[class.sortable]': '!!shSort()',\n    '[attr.tabindex]': 'shSort() ? \"0\" : null',\n    '(click)': 'shSort() ? toggleSort(",
-        "returnType": "null',\n    '(keydown.enter)': 'shSort() ? toggleSort() : null',\n    '(keydown.space)': 'shSort() ? toggleSort($event) : null',\n    '[attr.aria-sort]': 'shSort() ? ariaSort() : null',\n    '[class.sort-asc]': 'sortAsc()',\n    '[class.sort-desc]': 'sortDesc()',\n  },\n})\nexport class ShipSort",
+        "parameters": "this.#animationFrameRequest);\n    }\n  }\n}\n\n@Directive({\n  selector: '[shSort]',\n  standalone: true,\n  host: {\n    role: 'columnheader',\n    '[class.sortable]': '!!shSort()',\n    '[attr.tabindex]': 'shSort() ? \"0\" : null',\n    '(click)': 'shSort() ? toggleSort(",
+        "returnType": "null',\n    '[attr.aria-sort]': 'shSort() ? ariaSort() : null',\n    '[class.sort-asc]': 'sortAsc()',\n    '[class.sort-desc]': 'sortDesc()',\n  },\n})\nexport class ShipSort",
+        "description": ""
+      },
+      {
+        "name": "onKeyDown",
+        "parameters": "event: KeyboardEvent",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "onCleanup",
+        "parameters": "() => observer.disconnect());\n    }\n  });\n\n  bodyEffect = effect(() => {\n    const body = this.tbody()?.nativeElement;\n    const head = this.thead()?.nativeElement;\n\n    if (!body || !head) return;\n\n    const stickyHeaderHeight = this.stickyHeaderHeight();\n\n    queueMicrotask(() => {\n      const hasStickyRowHeaderStartElement = head.querySelectorAll('tr.sticky').length > 0;\n      const stickyBodyRows = body.querySelectorAll('tr.sticky');\n      const hasStickyRowStartElement = stickyBodyRows.length > 0;\n\n      if (hasStickyRowStartElement && hasStickyRowHeaderStartElement",
+        "returnType": "any",
         "description": ""
       },
       {
@@ -1565,6 +2001,12 @@
         "parameters": "row: any, col: ShipTableColumn",
         "returnType": "any",
         "description": ""
+      },
+      {
+        "name": "formatDate",
+        "parameters": "value: any",
+        "returnType": "string",
+        "description": ""
       }
     ],
     "cssVariables": [
@@ -2772,6 +3214,12 @@
         "parameters": "",
         "returnType": "any",
         "description": ""
+      },
+      {
+        "name": "handleKeyDown",
+        "parameters": "event: KeyboardEvent",
+        "returnType": "any",
+        "description": ""
       }
     ],
     "cssVariables": [],
@@ -4386,6 +4834,135 @@
       }
     ]
   },
+  {
+    "name": "ShipA11yKeybindingsDirective",
+    "selector": "[shA11yKeybinding]",
+    "path": "core/projects/ship-ui/ship-a11y-keybindings/ship-a11y-keybindings.directive.ts",
+    "description": "### Overview & Accessibility\n\nThe A11y Keybindings engine provides a unified system for handling keyboard shortcuts. The\n`[shA11yKeybinding]` directive dynamically sets standard `aria-keyshortcuts` attributes\non host elements to announce active hotkeys to assistive technologies.\n\n### Provider Overrides\n\nDefault shortcuts registered by components can be overridden globally at the application level.\nProvide the `SHIP_A11Y_KEYBINDINGS_OVERRIDE` injection token with a mapping object:\n`&#123; provide: SHIP_A11Y_KEYBINDINGS_OVERRIDE, useValue: &#123; 'action.name': 'ctrl+s' &#125; &#125;`.\n\n### OS Adaptive Keys (Command vs Control)\n\nWe support the `ctrlOrCmd` modifier keyword in shortcuts. It maps dynamically at runtime:\nresolves to `Command (⌘)` on macOS and `Control (Ctrl)` on Windows/Linux. Display formats are also customized for each OS (e.g. `⌘⇧K` vs `Ctrl+Shift+K`).\n\n### Collisions & Input Handling\n\nWhen in `mode=\"global\"`, the directive automatically ignores keypresses that originate\nfrom input boxes, selects, textareas, or content-editables (unless modifier keys like Ctrl, Cmd, or Alt are pressed),\nensuring keyboard shortcuts do not interfere with typing.",
+    "keywords": [
+      "accessibility",
+      "keybindings",
+      "hotkeys",
+      "shortcuts",
+      "keyboard",
+      "global",
+      "local",
+      "cmd",
+      "ctrl",
+      "modifiers",
+      "focus"
+    ],
+    "inputs": [
+      {
+        "name": "mode",
+        "type": "'global' | 'local'",
+        "description": "The registered action name (e.g. 'table.next-page', 'dialog.close'). / shA11yKeybinding = input.required<string>(); /** Defines whether the keybinding listener is 'local' (host element keydown) or 'global' (window keydown). Default is 'local'.",
+        "defaultValue": "'local'"
+      },
+      {
+        "name": "preventDefault",
+        "type": "boolean",
+        "description": "The registered action name (e.g. 'table.next-page', 'dialog.close'). / shA11yKeybinding = input.required<string>(); /** Defines whether the keybinding listener is 'local' (host element keydown) or 'global' (window keydown). Default is 'local'. / mode = input<'global' | 'local'>('local'); /** Whether to prevent the default action when the keybinding matches.",
+        "defaultValue": "true"
+      },
+      {
+        "name": "stopPropagation",
+        "type": "boolean",
+        "description": "The registered action name (e.g. 'table.next-page', 'dialog.close'). / shA11yKeybinding = input.required<string>(); /** Defines whether the keybinding listener is 'local' (host element keydown) or 'global' (window keydown). Default is 'local'. / mode = input<'global' | 'local'>('local'); /** Whether to prevent the default action when the keybinding matches. / preventDefault = input<boolean>(true); /** Whether to stop event propagation when the keybinding matches.",
+        "defaultValue": "true"
+      }
+    ],
+    "outputs": [
+      {
+        "name": "triggered",
+        "type": "KeyboardEvent",
+        "description": "The registered action name (e.g. 'table.next-page', 'dialog.close'). / shA11yKeybinding = input.required<string>(); /** Defines whether the keybinding listener is 'local' (host element keydown) or 'global' (window keydown). Default is 'local'. / mode = input<'global' | 'local'>('local'); /** Whether to prevent the default action when the keybinding matches. / preventDefault = input<boolean>(true); /** Whether to stop event propagation when the keybinding matches. / stopPropagation = input<boolean>(true); /** Event emitted when the keybinding is triggered."
+      }
+    ],
+    "methods": [
+      {
+        "name": "effect",
+        "parameters": "(onCleanup) => {\n      if (this.mode() === 'global' && isPlatformBrowser(this.#platformId)",
+        "returnType": "any",
+        "description": ""
+      },
+      {
+        "name": "onCleanup",
+        "parameters": "() => {\n          window.removeEventListener('keydown', listener);\n        });\n      }\n    });\n  }\n\n  /**\n   * Local keydown listener when mode is 'local'\n   */\n  @HostListener('keydown', ['$event'])\n  onKeyDown(event: KeyboardEvent",
+        "returnType": "void",
+        "description": ""
+      }
+    ],
+    "cssVariables": [],
+    "examples": [
+      {
+        "name": "basic-keybindings",
+        "html": "<div class=\"example-wrapper\">\n  <div class=\"card-grid\">\n    <div class=\"card\">\n      <h3>Local Trigger</h3>\n      <p class=\"description\">\n        Only triggers when the button itself is focused.\n      </p>\n      <div class=\"shortcut-info\">\n        Shortcut: <code class=\"kbd-badge\">{{ service.getDisplayShortcut('example.increment-local') }}</code>\n      </div>\n      <button \n        shButton \n        [shA11yKeybinding]=\"'example.increment-local'\" \n        mode=\"local\" \n        (triggered)=\"incrementLocal()\">\n        Local Increment ({{ localCounter() }})\n      </button>\n    </div>\n\n    <div class=\"card\">\n      <h3>Global Trigger</h3>\n      <p class=\"description\">\n        Triggers from anywhere on the page (ignored when focused in inputs).\n      </p>\n      <div class=\"shortcut-info\">\n        Shortcut: <code class=\"kbd-badge\">{{ service.getDisplayShortcut('example.increment-global') }}</code>\n      </div>\n      <button \n        shButton \n        variant=\"flat\"\n        [shA11yKeybinding]=\"'example.increment-global'\" \n        mode=\"global\" \n        (triggered)=\"incrementGlobal()\">\n        Global Increment ({{ globalCounter() }})\n      </button>\n    </div>\n  </div>\n\n  <div class=\"controls-panel\">\n    <button shButton variant=\"outlined\" size=\"small\" (click)=\"changeShortcut()\">\n      Swap Local Shortcut to: {{ service.getShortcut('example.increment-local') === 'enter' ? 'Space' : 'Enter' }}\n    </button>\n  </div>\n</div>\n",
+        "ts": "import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core';\nimport { ShipA11yKeybindingsDirective, ShipA11yKeybindingsService } from '@ship-ui/core/ship-a11y-keybindings';\nimport { ShipButton } from '@ship-ui/core/ship-button';\n\n@Component({\n  selector: 'app-basic-keybindings',\n  imports: [ShipA11yKeybindingsDirective, ShipButton],\n  templateUrl: './basic-keybindings.html',\n  styleUrl: './basic-keybindings.scss',\n  changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class BasicKeybindingsComponent {\n  readonly service = inject(ShipA11yKeybindingsService);\n\n  localCounter = signal(0);\n  globalCounter = signal(0);\n\n  constructor() {\n    // Register defaults for our example actions\n    this.service.registerDefaults({\n      'example.increment-local': 'enter',\n      'example.increment-global': 'ctrlOrCmd+shift+s',\n    });\n  }\n\n  incrementLocal() {\n    this.localCounter.update((c) => c + 1);\n  }\n\n  incrementGlobal() {\n    this.globalCounter.update((c) => c + 1);\n  }\n\n  changeShortcut() {\n    // Override a keybinding at runtime\n    const currentLocal = this.service.getShortcut('example.increment-local');\n    const nextLocal = currentLocal === 'enter' ? 'space' : 'enter';\n\n    this.service.registerOverrides({\n      'example.increment-local': nextLocal,\n    });\n  }\n}\n"
+      }
+    ]
+  },
+  {
+    "name": "ShipA11yKeybindingsService",
+    "selector": "ship-a11y-keybindings-service",
+    "path": "core/projects/ship-ui/ship-a11y-keybindings/ship-a11y-keybindings.service.ts",
+    "description": "### Overview & Accessibility\n\nThe A11y Keybindings engine provides a unified system for handling keyboard shortcuts. The\n`[shA11yKeybinding]` directive dynamically sets standard `aria-keyshortcuts` attributes\non host elements to announce active hotkeys to assistive technologies.\n\n### Provider Overrides\n\nDefault shortcuts registered by components can be overridden globally at the application level.\nProvide the `SHIP_A11Y_KEYBINDINGS_OVERRIDE` injection token with a mapping object:\n`&#123; provide: SHIP_A11Y_KEYBINDINGS_OVERRIDE, useValue: &#123; 'action.name': 'ctrl+s' &#125; &#125;`.\n\n### OS Adaptive Keys (Command vs Control)\n\nWe support the `ctrlOrCmd` modifier keyword in shortcuts. It maps dynamically at runtime:\nresolves to `Command (⌘)` on macOS and `Control (Ctrl)` on Windows/Linux. Display formats are also customized for each OS (e.g. `⌘⇧K` vs `Ctrl+Shift+K`).\n\n### Collisions & Input Handling\n\nWhen in `mode=\"global\"`, the directive automatically ignores keypresses that originate\nfrom input boxes, selects, textareas, or content-editables (unless modifier keys like Ctrl, Cmd, or Alt are pressed),\nensuring keyboard shortcuts do not interfere with typing.",
+    "keywords": [
+      "accessibility",
+      "keybindings",
+      "hotkeys",
+      "shortcuts",
+      "keyboard",
+      "global",
+      "local",
+      "cmd",
+      "ctrl",
+      "modifiers",
+      "focus"
+    ],
+    "inputs": [],
+    "outputs": [],
+    "methods": [
+      {
+        "name": "registerDefaults",
+        "parameters": "defaults: Record<string, string>",
+        "returnType": "void",
+        "description": "Returns true if the platform is running on macOS. / get isMac(): boolean { if (!isPlatformBrowser(this.#platformId)) return false; return navigator.userAgent.toLowerCase().includes('mac'); } constructor() { this.registerDefaults(DEFAULT_KEYBINDINGS); if (this.#overrides) { this.registerOverrides(this.#overrides); } } /** Registers default shortcuts for actions. If an override already exists for a given action, the override takes precedence."
+      },
+      {
+        "name": "registerOverrides",
+        "parameters": "overrides: Record<string, string>",
+        "returnType": "void",
+        "description": "Returns true if the platform is running on macOS. / get isMac(): boolean { if (!isPlatformBrowser(this.#platformId)) return false; return navigator.userAgent.toLowerCase().includes('mac'); } constructor() { this.registerDefaults(DEFAULT_KEYBINDINGS); if (this.#overrides) { this.registerOverrides(this.#overrides); } } /** Registers default shortcuts for actions. If an override already exists for a given action, the override takes precedence. / registerDefaults(defaults: Record<string, string>): void { for (const [action, shortcut] of Object.entries(defaults)) { this.#defaults.set(action, shortcut); // If we don't have an override/binding for this action, set it as the active binding if (!this.#bindings.has(action)) { this.#bindings.set(action, shortcut); } } } /** Registers overrides for actions. Overwrites any existing or default bindings."
+      },
+      {
+        "name": "getShortcut",
+        "parameters": "action: string",
+        "returnType": "string | undefined",
+        "description": "Returns true if the platform is running on macOS. / get isMac(): boolean { if (!isPlatformBrowser(this.#platformId)) return false; return navigator.userAgent.toLowerCase().includes('mac'); } constructor() { this.registerDefaults(DEFAULT_KEYBINDINGS); if (this.#overrides) { this.registerOverrides(this.#overrides); } } /** Registers default shortcuts for actions. If an override already exists for a given action, the override takes precedence. / registerDefaults(defaults: Record<string, string>): void { for (const [action, shortcut] of Object.entries(defaults)) { this.#defaults.set(action, shortcut); // If we don't have an override/binding for this action, set it as the active binding if (!this.#bindings.has(action)) { this.#bindings.set(action, shortcut); } } } /** Registers overrides for actions. Overwrites any existing or default bindings. / registerOverrides(overrides: Record<string, string>): void { for (const [action, shortcut] of Object.entries(overrides)) { this.#bindings.set(action, shortcut); } } /** Retrieves the active shortcut string for a registered action."
+      },
+      {
+        "name": "getDefaultShortcut",
+        "parameters": "action: string",
+        "returnType": "string | undefined",
+        "description": "Returns true if the platform is running on macOS. / get isMac(): boolean { if (!isPlatformBrowser(this.#platformId)) return false; return navigator.userAgent.toLowerCase().includes('mac'); } constructor() { this.registerDefaults(DEFAULT_KEYBINDINGS); if (this.#overrides) { this.registerOverrides(this.#overrides); } } /** Registers default shortcuts for actions. If an override already exists for a given action, the override takes precedence. / registerDefaults(defaults: Record<string, string>): void { for (const [action, shortcut] of Object.entries(defaults)) { this.#defaults.set(action, shortcut); // If we don't have an override/binding for this action, set it as the active binding if (!this.#bindings.has(action)) { this.#bindings.set(action, shortcut); } } } /** Registers overrides for actions. Overwrites any existing or default bindings. / registerOverrides(overrides: Record<string, string>): void { for (const [action, shortcut] of Object.entries(overrides)) { this.#bindings.set(action, shortcut); } } /** Retrieves the active shortcut string for a registered action. / getShortcut(action: string): string | undefined { return this.#bindings.get(action); } /** Retrieves the default shortcut string for a registered action."
+      },
+      {
+        "name": "getDisplayShortcut",
+        "parameters": "action: string",
+        "returnType": "string | undefined",
+        "description": "Returns true if the platform is running on macOS. / get isMac(): boolean { if (!isPlatformBrowser(this.#platformId)) return false; return navigator.userAgent.toLowerCase().includes('mac'); } constructor() { this.registerDefaults(DEFAULT_KEYBINDINGS); if (this.#overrides) { this.registerOverrides(this.#overrides); } } /** Registers default shortcuts for actions. If an override already exists for a given action, the override takes precedence. / registerDefaults(defaults: Record<string, string>): void { for (const [action, shortcut] of Object.entries(defaults)) { this.#defaults.set(action, shortcut); // If we don't have an override/binding for this action, set it as the active binding if (!this.#bindings.has(action)) { this.#bindings.set(action, shortcut); } } } /** Registers overrides for actions. Overwrites any existing or default bindings. / registerOverrides(overrides: Record<string, string>): void { for (const [action, shortcut] of Object.entries(overrides)) { this.#bindings.set(action, shortcut); } } /** Retrieves the active shortcut string for a registered action. / getShortcut(action: string): string | undefined { return this.#bindings.get(action); } /** Retrieves the default shortcut string for a registered action. / getDefaultShortcut(action: string): string | undefined { return this.#defaults.get(action); } /** Gets a formatted, user-friendly shortcut string for display. E.g. 'ctrlOrCmd+Shift+KeyK' -> '⌘⇧K' on macOS, 'Ctrl+Shift+K' on Windows/Linux. Supports comma-separated multiple shortcuts (e.g. 'ArrowRight, d' -> 'ArrowRight, D')."
+      }
+    ],
+    "cssVariables": [],
+    "examples": [
+      {
+        "name": "basic-keybindings",
+        "html": "<div class=\"example-wrapper\">\n  <div class=\"card-grid\">\n    <div class=\"card\">\n      <h3>Local Trigger</h3>\n      <p class=\"description\">\n        Only triggers when the button itself is focused.\n      </p>\n      <div class=\"shortcut-info\">\n        Shortcut: <code class=\"kbd-badge\">{{ service.getDisplayShortcut('example.increment-local') }}</code>\n      </div>\n      <button \n        shButton \n        [shA11yKeybinding]=\"'example.increment-local'\" \n        mode=\"local\" \n        (triggered)=\"incrementLocal()\">\n        Local Increment ({{ localCounter() }})\n      </button>\n    </div>\n\n    <div class=\"card\">\n      <h3>Global Trigger</h3>\n      <p class=\"description\">\n        Triggers from anywhere on the page (ignored when focused in inputs).\n      </p>\n      <div class=\"shortcut-info\">\n        Shortcut: <code class=\"kbd-badge\">{{ service.getDisplayShortcut('example.increment-global') }}</code>\n      </div>\n      <button \n        shButton \n        variant=\"flat\"\n        [shA11yKeybinding]=\"'example.increment-global'\" \n        mode=\"global\" \n        (triggered)=\"incrementGlobal()\">\n        Global Increment ({{ globalCounter() }})\n      </button>\n    </div>\n  </div>\n\n  <div class=\"controls-panel\">\n    <button shButton variant=\"outlined\" size=\"small\" (click)=\"changeShortcut()\">\n      Swap Local Shortcut to: {{ service.getShortcut('example.increment-local') === 'enter' ? 'Space' : 'Enter' }}\n    </button>\n  </div>\n</div>\n",
+        "ts": "import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core';\nimport { ShipA11yKeybindingsDirective, ShipA11yKeybindingsService } from '@ship-ui/core/ship-a11y-keybindings';\nimport { ShipButton } from '@ship-ui/core/ship-button';\n\n@Component({\n  selector: 'app-basic-keybindings',\n  imports: [ShipA11yKeybindingsDirective, ShipButton],\n  templateUrl: './basic-keybindings.html',\n  styleUrl: './basic-keybindings.scss',\n  changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class BasicKeybindingsComponent {\n  readonly service = inject(ShipA11yKeybindingsService);\n\n  localCounter = signal(0);\n  globalCounter = signal(0);\n\n  constructor() {\n    // Register defaults for our example actions\n    this.service.registerDefaults({\n      'example.increment-local': 'enter',\n      'example.increment-global': 'ctrlOrCmd+shift+s',\n    });\n  }\n\n  incrementLocal() {\n    this.localCounter.update((c) => c + 1);\n  }\n\n  incrementGlobal() {\n    this.globalCounter.update((c) => c + 1);\n  }\n\n  changeShortcut() {\n    // Override a keybinding at runtime\n    const currentLocal = this.service.getShortcut('example.increment-local');\n    const nextLocal = currentLocal === 'enter' ? 'space' : 'enter';\n\n    this.service.registerOverrides({\n      'example.increment-local': nextLocal,\n    });\n  }\n}\n"
+      }
+    ]
+  },
   {
     "name": "ShipButton",
     "selector": "[shButton]",