@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/ai/skills/concorde/rules/styling.md

@@ -0,0 +1,46 @@
+# Styling
+
+Docs: [Theming](https://concorde.supersoniks.org/docs/getting-started/theming). Which parts and states components offer: [composition.md](composition.md).
+
+## Theme
+
+One `<sonic-theme>` at the app root sets the tokens; popovers, modals and toasts mount under it.
+
+```ts
+html`<sonic-theme theme="auto" color font class="block bg-base min-h-screen">…</sonic-theme>`;
+```
+
+`theme="light" | "dark" | "auto"` picks a palette; without it, only your `--sc-*` overrides apply. To brand, override the **essential tokens** only (fills, `-content` pairs, `--sc-base-*`, `--sc-rounded`, fonts) on `sonic-theme` or `:root`. Never copy derived variables (`--sc-rounded-sm`, `--sc-btn-*`, …).
+
+## Rules
+
+1. **Compose components first.** `sonic-button`, `sonic-badge`, `sonic-alert`, `sonic-card`, `sonic-divider`, `sonic-menu`, `sonic-icon`, form fields… before hand-made markup ([composition.md](composition.md)).
+2. **Configure components with attributes, not CSS.** `type` (`primary` · `neutral` · `success` · `warning` · `danger` · `info`), `variant` (`outline` · `ghost` · `link`), `size` (`2xs` … `2xl`), `shape`, `status`. `class` on a `sonic-*` element is for layout only (width, margin, grid placement). No `::part()`, no private `--sc_*` variables.
+3. **Semantic tokens only.** Fills and their text go in pairs: `bg-primary text-primary-content`, `bg-danger text-danger-content`. Surfaces: `bg-base text-content`. Borders and muted UI: the neutral scale (`border-neutral-200`, `bg-neutral-50`, `text-neutral-600`). Never raw colors: no hex / rgb, no Tailwind palette (`blue-500`). A missing color becomes a theme token.
+4. **No `dark:` overrides.** Dark mode comes from `sonic-theme`; tokens switch by themselves.
+5. **Shape from tokens.** `rounded` / `rounded-lg`, `shadow` / `shadow-md` and `border` map to `--sc-rounded*`, `--sc-shadow*`, `--sc-border-width`. Avoid arbitrary values when they could be replaced easily (`rounded-[6px]`, `p-[13px]`).
+6. **Layout with `flex` / `grid` + `gap`.** Not `space-x-*` / `space-y-*` or margins between siblings. `size-10` instead of `w-10 h-10`.
+7. **Conditional classes with `classMap`** (`lit/directives/class-map.js`), dynamic values with `styleMap`. No template-literal ternaries inside `class="…"`.
+8. **Accessible by default.** Every field has a `label`. An icon-only button (`shape="circle"` / `"square"`) gets an `aria-label`; `sonic-icon` is `aria-hidden`.
+
+## In a component
+
+Tailwind classes apply inside a shadow root only if the component includes the project's Tailwind styles in `static styles`. Otherwise, write `css` with the tokens:
+
+```ts
+static styles = css`
+  :host { display: flex; gap: 0.5rem; }
+  .panel {
+    background: var(--sc-base);
+    color: var(--sc-base-content);
+    border: var(--sc-border-width) solid var(--sc-base-200);
+    border-radius: var(--sc-rounded);
+  }
+`;
+```
+
+```ts
+html`<div class=${classMap({ "bg-warning text-warning-content": delayed, "bg-base": !delayed })}>
+  <sonic-badge type=${delayed ? "warning" : "success"} size="sm">${status}</sonic-badge>
+</div>`;
+```

package/ai/skills/concorde/rules/troubleshooting.md

@@ -0,0 +1,45 @@
+# Troubleshooting
+
+Symptom → usual cause → fix. Check these before reading framework source.
+
+## Data
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Value never updates in the view | Subscribed to a parent object; a child `set` mutates it in place without notifying | `sub(key.leaf)` or `@subscribe(key.leaf)` |
+| Same, with a leaf key | `@subscribe` without `@state()` | Add `@state()` |
+| Value frozen in a template | `get(key)` in `html` (one-time snapshot) | `sub(key)` |
+| `sub()` renders nothing | The store has no value yet, or a placeholder is `null` / `undefined` | Set an initial value; check the host property |
+| Store value overwritten when the component connects | `@publish` publishes a defined initializer on connect | Leave the property `undefined` to keep the store value |
+| `@handle` method crashes on start | It runs on connect and on every assignment, `null` included | Guard nullish values, or `{ waitForAllDefined: true }` / `Skip.Nullish` |
+| `get` / `set` / `dp` throw about a placeholder | A key with `${…}` reached imperative code | Decorator, or build the resolved key (`usersKey[id]`) |
+| Decorator with a dynamic path does nothing | A placeholder property is `null` / `undefined` (or `""` with `skipEmptyPlaceholder`) | Set the host property |
+
+## HTTP
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `@get` never sends | No `serviceURL` on an ancestor (the GET waits for it); common in modals and portals | `<sonic-scope serviceURL>` around it, or `@get(endpoint, apiConfigKey)` |
+| POST sent on every keystroke | `@post` sends on each body mutation by default | `{ autoPostOnBodyMutation: false }` + `send()` |
+| Property `undefined` after the request | Read `this.board.flights` instead of the `ApiResult` | `this.board?.result?.flights` |
+
+## Lists and forms
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| List renders nothing | `items=${fn}` without the dot, so the function is lost | `.items=${fn}` (same for `.noItems` / `.skeleton` / `.separator`) |
+| `sonic-list` never requests | No `fetch` attribute | Add `fetch` |
+| List empty although the response has data | `key` does not name the array in the response | Set `key` to the array property |
+| `sonic-queue` loads one batch only | No `$offset` in `dataProviderExpression` | `…?offset=$offset&limit=$limit` |
+| Queue ignores the filter form | `dataFilterProvider` is not the form's store, or fields lack `name` | Same key path on both; reload follows after a 400 ms debounce |
+| Field value not in the store | Missing `name`, or no `formDataProvider` on the field or an ancestor (`dataProvider` does not count) | Add both; pass `key.path`, not the key |
+
+## Rendering and styling
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| A `sonic-*` tag shows nothing | Its module was never imported | `import "@supersoniks/concorde/<name>"` |
+| Tailwind classes ignored inside a component | The shadow root does not include the Tailwind styles | Add them to `static styles`, or use `css` with `var(--sc-*)` |
+| Modal, popover or toast unstyled | No `sonic-theme` ancestor: they mount under the nearest one | Wrap the app in `sonic-theme` |
+| `hideModal` button does not close the modal | The button is not inside `sonic-modal-actions` | Move it there |
+| `get` is not a function / wrong `get` | Decorator `get` (`/decorators`) and store `get` (`/utils`) collide | Alias one: `get as getRequest` |

package/build-infos.json

@@ -1 +1 @@
-{"date":1793005010}
+{"date":1793309731}