@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/src/docs/components/docs-demo-sources.ts

@@ -2,7 +2,7 @@ import { css, html, LitElement, nothing } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
 import { unsafeHTML } from "lit/directives/unsafe-html.js";
 import { tailwind } from "../tailwind";
-import { docsSourceLinks, type DocsSource } from "./docs-source-link";
+import type { DocsSource } from "./docs-source-link";
 import { DOCS_SOURCE_RAW } from "./docs-source-raw";
 import { resolveSourceExcerpt } from "./docs-source-excerpt";
 import { docsCodeCSS, highlightDocsCode } from "../shiki";
@@ -24,7 +24,7 @@ export const DOCS_LIT_DEMO_REGISTRY: Record<string, DocsLitDemoConfig> = {
     sources: [
       {
         path: "src/docs/example/docs-boarding-pass-demo.ts",
-        line: 19,
+        line: 18,
         label: "docs-boarding-pass-demo",
       },
     ],
@@ -42,80 +42,39 @@ export const DOCS_LIT_DEMO_REGISTRY: Record<string, DocsLitDemoConfig> = {
     sources: [
       {
         path: "src/docs/example/docs-toggle-demos.ts",
-        line: 49,
+        line: 50,
         label: "docs-toggle-loader-demo",
       },
     ],
   },
-  "docs-joke-search-demo": {
-    sources: [
-      { path: "src/docs/example/docs-joke-demos.ts", line: 111, label: "search" },
-    ],
-  },
-  "docs-joke-lang-demo": {
+  "docs-flight-search-demo": {
     sources: [
-      { path: "src/docs/example/docs-joke-demos.ts", line: 136, label: "lang" },
+      { path: "src/docs/example/docs-flight-demos.ts", line: 65, label: "search" },
     ],
   },
-  "docs-joke-blacklist-demo": {
+  "docs-flight-direction-demo": {
     sources: [
-      { path: "src/docs/example/docs-joke-demos.ts", line: 181, label: "blacklist" },
+      { path: "src/docs/example/docs-flight-demos.ts", line: 85, label: "direction" },
     ],
   },
-  "docs-joke-blacklist-radio-demo": {
+  "docs-flight-status-radio-demo": {
     sources: [
-      { path: "src/docs/example/docs-joke-demos.ts", line: 212, label: "radio" },
+      { path: "src/docs/example/docs-flight-demos.ts", line: 106, label: "radio" },
     ],
   },
-  "docs-joke-blacklist-switch-demo": {
+  "docs-flight-delayed-switch-demo": {
     sources: [
-      { path: "src/docs/example/docs-joke-demos.ts", line: 256, label: "switch" },
+      { path: "src/docs/example/docs-flight-demos.ts", line: 129, label: "switch" },
     ],
   },
   "docs-queue-users-demo": {
     sources: [
-      { path: "src/docs/example/docs-queue-demos.ts", line: 66, label: "users" },
+      { path: "src/docs/example/docs-queue-demos.ts", line: 45, label: "filter" },
     ],
   },
   "docs-queue-geo-demo": {
     sources: [
-      { path: "src/docs/example/docs-queue-demos.ts", line: 38, label: "geo" },
-    ],
-  },
-  "docs-input-autocomplete-basic-demo": {
-    sources: [
-      {
-        path: "src/docs/example/docs-input-autocomplete-demos.ts",
-        line: 11,
-        label: "basic",
-      },
-    ],
-  },
-  "docs-input-autocomplete-code-demo": {
-    sources: [
-      {
-        path: "src/docs/example/docs-input-autocomplete-demos.ts",
-        line: 36,
-        label: "code",
-      },
-    ],
-  },
-  "docs-input-autocomplete-select-demo": {
-    sources: [
-      {
-        path: "src/docs/example/docs-input-autocomplete-demos.ts",
-        line: 63,
-        label: "select",
-      },
-    ],
-  },
-  "docs-input-autocomplete-keyboard-demo": {
-    sources: [
-      {
-        path: "src/docs/example/docs-input-autocomplete-demos.ts",
-        line: 91,
-        label: "keyboard",
-      },
+      { path: "src/docs/example/docs-queue-demos.ts", line: 26, label: "lazy load" },
     ],
   },
   "docs-users-list": {
@@ -136,29 +95,24 @@ export const DOCS_LIT_DEMO_REGISTRY: Record<string, DocsLitDemoConfig> = {
     sources: [
       {
         path: "src/docs/example/docs-jsonata-demos.ts",
-        line: 69,
+        line: 73,
         label: "totals",
       },
     ],
   },
   "docs-list-alternate-demo": {
     sources: [
-      { path: "src/docs/example/docs-list-demos.ts", line: 51, label: "alternate" },
-    ],
-  },
-  "docs-list-template-key-demo": {
-    sources: [
-      { path: "src/docs/example/docs-list-demos.ts", line: 79, label: "templateKey" },
+      { path: "src/docs/example/docs-list-demos.ts", line: 9, label: "alternate" },
     ],
   },
   "docs-list-separator-demo": {
     sources: [
-      { path: "src/docs/example/docs-list-demos.ts", line: 118, label: "separator" },
+      { path: "src/docs/example/docs-list-demos.ts", line: 39, label: "separator" },
     ],
   },
   "docs-list-extract-values-demo": {
     sources: [
-      { path: "src/docs/example/docs-list-demos.ts", line: 146, label: "extractValues" },
+      { path: "src/docs/example/docs-list-demos.ts", line: 75, label: "extractValues" },
     ],
   },
   "docs-router-basic-demo": {
@@ -237,14 +191,14 @@ export const DOCS_LIT_DEMO_REGISTRY: Record<string, DocsLitDemoConfig> = {
   },
   "docs-api-config-scoped-attrs-demo": {
     sources: [
-      { path: "src/docs/example/docs-api-config-demos.ts", line: 162, label: "scope" },
+      { path: "src/docs/example/docs-api-config-demos.ts", line: 161, label: "scope" },
     ],
   },
   "docs-api-config-events-token-demo": {
     sources: [
       {
         path: "src/docs/example/docs-api-config-demos.ts",
-        line: 191,
+        line: 190,
         label: "eventsApiToken",
       },
     ],
@@ -261,49 +215,27 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
     { path: "src/docs/example/users.ts", label: "docs-user" },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
   ],
-  "docs-joke-search-demo": [
-    { path: "src/docs/example/docs-joke-demos.ts", label: "joke demos" },
+  "docs-flight-search-demo": [
+    { path: "src/docs/example/docs-flight-demos.ts", label: "flight demos" },
+    { path: "src/docs/mock-api/flights.ts", label: "mock flights" },
   ],
   "docs-jsonata-space-cats-demo": [
     { path: "src/docs/example/docs-jsonata-demos.ts", label: "jsonata demos" },
-    { path: "src/docs/mock-api/fixtures-jsonata.ts", label: "fixtures" },
   ],
   "docs-jsonata-table-totals-demo": [
     { path: "src/docs/example/docs-jsonata-demos.ts", label: "jsonata demos" },
-    { path: "src/docs/mock-api/fixtures-jsonata.ts", label: "fixtures" },
   ],
-  "docs-joke-lang-demo": [
-    { path: "src/docs/example/docs-joke-demos.ts", label: "joke demos" },
+  "docs-flight-direction-demo": [
+    { path: "src/docs/example/docs-flight-demos.ts", label: "flight demos" },
+    { path: "src/docs/mock-api/flights.ts", label: "mock flights" },
   ],
   "docs-queue-geo-demo": [
     { path: "src/docs/example/docs-queue-demos.ts", label: "queue demos" },
-  ],
-  "docs-input-autocomplete-basic-demo": [
-    {
-      path: "src/docs/example/docs-input-autocomplete-demos.ts",
-      label: "autocomplete demos",
-    },
-  ],
-  "docs-input-autocomplete-code-demo": [
-    {
-      path: "src/docs/example/docs-input-autocomplete-demos.ts",
-      label: "autocomplete demos",
-    },
-  ],
-  "docs-input-autocomplete-select-demo": [
-    {
-      path: "src/docs/example/docs-input-autocomplete-demos.ts",
-      label: "autocomplete demos",
-    },
-  ],
-  "docs-input-autocomplete-keyboard-demo": [
-    {
-      path: "src/docs/example/docs-input-autocomplete-demos.ts",
-      label: "autocomplete demos",
-    },
+    { path: "src/docs/mock-api/flights.ts", label: "mock flights" },
   ],
   "docs-queue-users-demo": [
     { path: "src/docs/example/docs-queue-demos.ts", label: "queue demos" },
+    { path: "src/docs/mock-api/flights.ts", label: "mock flights" },
   ],
   "docs-toggle-if-demo": [
     { path: "src/docs/example/docs-toggle-demos.ts", label: "toggle demos" },
@@ -314,34 +246,31 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-publish": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 32,
+      line: 81,
       label: "demo-publish",
     },
-    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
   ],
   "demo-subscribe-dynamic": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 269,
+      line: 263,
       label: "demo-subscribe-dynamic",
     },
-    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
   ],
   "demo-sub-template": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 238,
+      line: 244,
       label: "demo-sub-template",
     },
-    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
   ],
   "demo-api-get": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 86,
+      line: 121,
       label: "demo-api-get",
     },
-    { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
+    { path: "src/docs/example/decorators-demo-geo.ts", label: "flights API" },
     { path: "src/docs/mock-api/router.ts", label: "mock router" },
   ],
   "demo-api-get-method": [
@@ -349,28 +278,28 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
       label: "demo-api-get-method",
     },
-    { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
+    { path: "src/docs/example/decorators-demo-geo.ts", label: "flights API" },
   ],
   "demo-api-get-configuration-key": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 127,
+      line: 181,
       label: "demo-api-get-configuration-key",
     },
-    { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
+    { path: "src/docs/example/decorators-demo-geo.ts", label: "flights API" },
   ],
   "demo-api-get-publish-subscribe": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 178,
+      line: 217,
       label: "demo-api-get-publish-subscribe",
     },
-    { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
+    { path: "src/docs/example/decorators-demo-geo.ts", label: "flights API" },
   ],
   "demo-api-post": [
     {
       path: "src/docs/example/decorators-demo-post.ts",
-      line: 53,
+      line: 69,
       label: "demo-api-post",
     },
     { path: "src/docs/mock-api/router.ts", label: "mock router" },
@@ -385,15 +314,15 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-api-post-dynamic": [
     {
       path: "src/docs/example/decorators-demo-post.ts",
-      line: 143,
+      line: 144,
       label: "demo-api-post-dynamic",
     },
-    { path: "src/docs/mock-api/router.ts", label: "mock router (sessions sync)" },
+    { path: "src/docs/mock-api/router.ts", label: "mock router (check-in sync)" },
   ],
   "demo-api-post-publish": [
     {
       path: "src/docs/example/decorators-demo-post.ts",
-      line: 209,
+      line: 191,
       label: "demo-api-post-publish",
     },
     { path: "src/docs/mock-api/router.ts", label: "mock router" },
@@ -401,27 +330,24 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-handle": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 316,
+      line: 299,
       label: "demo-handle",
     },
-    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
   ],
   "demo-handle-dynamic": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
-      line: 351,
+      line: 330,
       label: "demo-handle-dynamic",
     },
-    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
   ],
   "demo-bind": [
-    { path: "src/docs/example/decorators-demo-bind-demos.ts", line: 14, label: "demo-bind" },
-    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
+    { path: "src/docs/example/decorators-demo-bind-demos.ts", line: 36, label: "demo-bind" },
   ],
   "demo-bind-reflect": [
     {
       path: "src/docs/example/decorators-demo-bind-demos.ts",
-      line: 56,
+      line: 74,
       label: "demo-bind-reflect",
     },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
@@ -429,18 +355,17 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-bind-dynamic": [
     {
       path: "src/docs/example/decorators-demo-bind-demos.ts",
-      line: 124,
+      line: 113,
       label: "demo-bind-dynamic",
     },
-    { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
   ],
   "demo-ancestor-attribute": [
-    { path: "src/docs/example/decorators-demo.ts", line: 35, label: "demo-ancestor-attribute" },
+    { path: "src/docs/example/decorators-demo.ts", line: 31, label: "demo-ancestor-attribute" },
   ],
   "demo-ancestor-attribute-dynamic-section": [
     {
       path: "src/docs/example/decorators-demo.ts",
-      line: 60,
+      line: 81,
       label: "demo-ancestor-attribute-dynamic",
     },
     {
@@ -450,25 +375,25 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
     },
   ],
   "demo-on-assign": [
-    { path: "src/docs/example/decorators-demo.ts", line: 43, label: "demo-on-assign" },
+    { path: "src/docs/example/decorators-demo.ts", line: 205, label: "demo-on-assign" },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
   ],
   "demo-on-assign-dynamic": [
     {
       path: "src/docs/example/decorators-demo.ts",
-      line: 94,
+      line: 253,
       label: "demo-on-assign-dynamic",
     },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
   ],
   "demo-auto-subscribe": [
-    { path: "src/docs/example/decorators-demo.ts", line: 211, label: "demo-auto-subscribe" },
+    { path: "src/docs/example/decorators-demo.ts", line: 366, label: "demo-auto-subscribe" },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
   ],
   "demo-wait-ancestors-section": [
     {
       path: "src/docs/example/decorators-demo.ts",
-      line: 278,
+      line: 430,
       label: "demo-wait-ancestors-section",
     },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
@@ -476,7 +401,7 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-wait-ancestors-multi-section": [
     {
       path: "src/docs/example/decorators-demo.ts",
-      line: 355,
+      line: 507,
       label: "demo-wait-ancestors-multi-section",
     },
     { path: "src/docs/example/decorators-demo-init.ts", label: "demo data" },
@@ -484,14 +409,14 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   "demo-wait-ancestors-static-section": [
     {
       path: "src/docs/example/decorators-demo.ts",
-      line: 462,
+      line: 610,
       label: "demo-wait-ancestors-static-section",
     },
   ],
   "demo-wait-ancestors-ready-section": [
     {
       path: "src/docs/example/decorators-demo.ts",
-      line: 432,
+      line: 584,
       label: "demo-wait-ancestors-ready-section",
     },
   ],
@@ -503,15 +428,6 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
     { path: "src/core/components/functional/list/list.demo.ts", label: "sonic-list-demo" },
     { path: "src/docs/mock-api/router.ts", label: "mock router" },
   ],
-  "queue-users-scroll": [
-    { path: "src/docs/example/docs-queue-demos.ts", label: "docs-queue-users-demo" },
-    { path: "src/docs/example/users.ts", label: "docs-user" },
-  ],
-  /** Inline list.md fetch demo — component + mock. */
-  "list-users-fetch": [
-    { path: "src/docs/example/docs-users-list.ts", label: "docs-users-list" },
-    { path: "src/docs/mock-api/router.ts", label: "mock API" },
-  ],
   "docs-submit-demo": [
     { path: "src/docs/example/docs-submit-demos.ts", label: "submit demo" },
     { path: "src/docs/mock-api/router.ts", label: "mock API (POST register)" },
@@ -603,7 +519,6 @@ export class DocsDemoSources extends LitElement {
     const sources = DOCS_DEMO_SOURCE_REGISTRY[this.forTag];
     if (!sources?.length) return nothing;
     return html`
-      ${docsSourceLinks(sources)}
       ${this.showCode && this.highlighted
         ? html`
             <pre

package/src/docs/components/docs-lit-demo.ts

@@ -2,7 +2,6 @@ import { css, html, LitElement, nothing, PropertyValues } from "lit";
 import { customElement, property } from "lit/decorators.js";
 import { unsafeHTML } from "lit/directives/unsafe-html.js";
 import { tailwind } from "../tailwind";
-import { docsSourceLinks } from "./docs-source-link";
 import {
   DOCS_LIT_DEMO_REGISTRY,
   type DocsLitDemoConfig,
@@ -40,7 +39,7 @@ export class DocsLitDemo extends LitElement {
         margin: 1.1rem 0;
       }
       .preview {
-        border: 1px solid var(--sc-border, #e5e5e5);
+        border: 1px solid var(--sc-border-color, #e5e5e5);
         border-radius: 0.375rem;
         padding: 1rem;
         margin-bottom: 0.75rem;
@@ -81,7 +80,6 @@ export class DocsLitDemo extends LitElement {
     const excerpt = this.excerpt;
 
     return html`
-      ${docsSourceLinks(cfg.sources)}
       <div class="preview" data-live-host></div>
       ${this.showCode && excerpt
         ? unsafeHTML(

package/src/docs/components/docs-source-link.ts

@@ -1,88 +1,6 @@
-import { html, nothing } from "lit";
-import "../../core/components/ui/button/button";
-import "../../core/components/ui/icon/icon";
-
-declare const __DOCS_EDITOR_AVAILABLE__: boolean;
-
 export type DocsSource = {
   path: string;
   line?: number;
   column?: number;
   label?: string;
 };
-
-const editorAvailable =
-  import.meta.env.DEV &&
-  typeof __DOCS_EDITOR_AVAILABLE__ !== "undefined" &&
-  __DOCS_EDITOR_AVAILABLE__;
-
-function openDocsSource(source: DocsSource, event: Event) {
-  event.preventDefault();
-  if (!editorAvailable) return;
-
-  const params = new URLSearchParams({
-    path: source.path,
-    line: String(source.line ?? 1),
-    column: String(source.column ?? 1),
-  });
-
-  void fetch(`/__docs/open?${params}`).catch(() => {
-    console.warn("[docs] Could not open in editor:", source.path);
-  });
-}
-
-export function docsSourceLink(source: DocsSource) {
-  if (!editorAvailable) return nothing;
-  const label = source.label ?? source.path.split("/").pop() ?? "source";
-  return html`
-    <sonic-button
-      variant="link"
-      size="2xs"
-      type="neutral"
-      title=${source.path}
-      @click=${(e: Event) => openDocsSource(source, e)}
-    >
-      <sonic-icon
-        library="heroicons"
-        name="arrow-top-right-on-square"
-        class="w-3 h-3 opacity-70"
-      ></sonic-icon>
-      ${label}
-    </sonic-button>
-  `;
-}
-
-export function docsSourceLinks(sources: DocsSource[]) {
-  if (sources.length === 0) return nothing;
-  return html`
-    <div
-      class="flex flex-wrap items-center gap-x-1 gap-y-1 mb-3 pb-3 border-b border-neutral-200/80 dark:border-neutral-700/80"
-    >
-      <span class="text-xs uppercase tracking-wide text-neutral-400 mr-1"
-        >Source</span
-      >
-      ${editorAvailable
-        ? sources.map((s, i) =>
-            i === 0
-              ? docsSourceLink(s)
-              : html`<span class="text-neutral-300 dark:text-neutral-600"
-                    >·</span
-                  >${docsSourceLink(s)}`,
-          )
-        : sources.map(
-            (s, i) => html`
-              ${i > 0
-                ? html`<span class="text-neutral-300 dark:text-neutral-600"
-                    >·</span
-                  >`
-                : nothing}
-              <span
-                class="text-xs font-mono text-neutral-500 dark:text-neutral-400"
-                title=${s.path}
-                >${s.label ?? s.path.split("/").pop()}</span
-              >
-            `,
-          )}
-    </div>
-  `;
-}

package/src/docs/decorators/ancestor-attribute.md

@@ -0,0 +1,59 @@
+# @ancestorAttribute
+
+Copies the value of an attribute from the nearest element that carries it (the host itself, then its ancestors, across shadow roots) into a class property. Use it to pick up a scope such as `dataProvider` without passing it down by hand, typically to feed a dynamic key of [@subscribe](/docs/decorators/subscribe).
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { ancestorAttribute } from "@supersoniks/concorde/decorators";
+
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
+
+## Read once at connect
+
+By default the value is read once, just before the component's `connectedCallback`, and never updated. The closest element with the attribute wins. If no ancestor has it, the property keeps its initial value.
+
+<sonic-code>
+  <template>
+<div dataProvider="flights.CN001" gate="B12">
+  <docs-demo-sources for="demo-ancestor-attribute"></docs-demo-sources>
+  <demo-ancestor-attribute></demo-ancestor-attribute>
+</div>
+  </template>
+</sonic-code>
+
+An attribute present without a value (`<div gate>`) resolves to `""`. A camelCase name also matches its lowercase form (`dataProvider` and `dataprovider`).
+
+## Follow DOM changes
+
+With `{ dynamic: true }`, the property stays in sync while the component is connected: when an ancestor changes the attribute, when a closer ancestor gains or loses it, and when the component is moved. When no ancestor has the attribute, the property becomes `null`. Add `@state()` so Lit re-renders on each assignment.
+
+<sonic-code language="typescript">
+  <template>
+@ancestorAttribute("dataProvider", { dynamic: true })
+@state()
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
+
+Change the parent or outer value, insert a closer wrapper, or remove an attribute: the child always shows the nearest one.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-ancestor-attribute-dynamic-section"></docs-demo-sources>
+    <demo-ancestor-attribute-dynamic-section></demo-ancestor-attribute-dynamic-section>
+  </template>
+</sonic-code>
+
+Keys of [@subscribe](/docs/decorators/subscribe) and [@bind](/docs/decorators/bind) that use the property as a placeholder (`"${dataProvider}"`) are re-resolved on each change.
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `attributeName` | `string` | Attribute to look up on the host, then on its ancestors |
+| `options.dynamic` | `boolean` (default `false`) | Keep the property in sync with attribute changes and reparenting until disconnect; assigns `null` when no ancestor has the attribute |

package/src/docs/decorators/auto-subscribe.md

@@ -0,0 +1,40 @@
+# @autoSubscribe
+
+Legacy decorator that re-runs a method whenever one of the store values it reads is assigned. For new code, prefer [@subscribe](/docs/decorators/subscribe) with a [`DataProviderKey`](/docs/misc/dataProviderKey): dependencies are explicit and typed.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { autoSubscribe } from "@supersoniks/concorde/decorators";
+import { get } from "@supersoniks/concorde/utils";
+
+@autoSubscribe()
+updateDisplay() {
+  this.total = get(passengersKey) + get(crewKey);
+}
+  </template>
+</sonic-code>
+
+## Tracked reads
+
+The method runs once after `connectedCallback`. Every store value read during that run becomes a dependency; assigning any of them runs the method again. Write the result to a `@state()` property (or call `requestUpdate()`) so the component re-renders.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-auto-subscribe"></docs-demo-sources>
+    <demo-auto-subscribe></demo-auto-subscribe>
+  </template>
+</sonic-code>
+
+## Notes
+
+- Several assignments in the same task trigger a single re-run (batched with `queueMicrotask`).
+- Keep reads unconditional: a value read only behind a condition becomes a dependency the first time that branch runs.
+- Subscriptions are removed in `disconnectedCallback`.
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| none | | `@autoSubscribe()` takes no argument; apply it to a method of a custom element |