@brandsync/wc 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @brandsync/wc
 
+## 1.13.0
+
+### Minor Changes
+
+- 91d53e4: Chat-widget developer-experience improvements.
+
+  **Theming.** Overriding `--bs-brand-50` … `--bs-brand-950` on any element with a `data-brand` attribute now re-derives every brand token (primary, text/icon action, primary border, focus rings) on that element, so per-tenant colours work anywhere in the tree. Outside `data-brand` nothing changes. New semantic token `--bs-color-primary-container-pressed`, used by `bs-chatbot-suggestion-button` instead of the raw `--bs-brand-200`. Unresolved `{...}` placeholder lines were removed from the vendored token stylesheet (the build now fails if they return).
+
+  **Behaviour change.** `bs-composer` no longer emits `bsSubmit` when the value is empty or whitespace-only.
+
+  **New props.** `bs-composer`: `hideAttach`, `hideMic`, `maxLength`, `loading`, and `*Label` props for every internal string. `bs-chatbot-header`: `hideNewChat`/`hideHistory`/`hideExpand`/`hideClose`, `*Label` props, and an `actions` slot. `bs-chatbot-response-action`: `liked`, `disliked`, `hideRegenerate`, `*Label` props. `bs-composer-status-banner`: `loading`, `closeLabel`. Label props (`closeLabel`, `dismissLabel`, `collapseLabel`, `loadingLabel`, ...) were also added to `bs-chatbot-feedback`, `bs-chatbot-sources-drawer`, `bs-dialog`, `bs-toast`, `bs-pagination`, `bs-input`, `bs-slider`, `bs-timepicker`, `bs-data-table`, `bs-attachment`, `bs-chip-input`, `bs-navigation-drawer` and both skeletons. Defaults are the previous English strings.
+
+  **New components.** `bs-skeleton`, `bs-spinner`, `bs-popover`, `bs-side-panel`, `bs-tooltip-trigger`, `bs-accordion-group`, `bs-message`, `bs-message-list`, `bs-citation-preview`.
+
+  **Package contents.** Now ships `CONVENTIONS.md`, `REFERENCE.md`, `reference.json` and typed `reference.d.ts` (parts, slots, CSS variables per component), a Tailwind preset (`@brandsync/wc/tailwind-preset`) and a Vitest/jsdom setup file (`@brandsync/wc/testing/vitest-setup`).
+
+## 1.12.1
+
+### Patch Changes
+
+- 4976988: `bs-input` `type="chip"`: the chip remove button is now `size="xs"` (20px, 12px icon). It was `md` (44px), so its hover/pressed area stuck out below the chip.
+
+  Also, for the record (shipped in 1.12.0 without a note): `bs-chatbot-header` side padding is now 16px, and its expand button's tooltip and accessible name read "Fullscreen" (was "Expand"; the expanded state reads "Exit fullscreen", was "Collapse"). `bs-composer` buttons are 44px with an 8px gap, and the human variant has a stronger border (`--bs-composer-border-human`).
+
 ## 1.12.0
 
 ### Minor Changes

package/CONVENTIONS.md

@@ -0,0 +1,109 @@
+# Customization surface convention
+
+Every component in this library exposes exactly three customization channels. Nothing outside these is
+overridable from consuming code — that's deliberate, not an oversight. It's what keeps every framework
+(React, Angular, Blazor, plain HTML) customizing the same component the same way, and keeps a consuming
+team from silently drifting off-brand.
+
+1. **CSS Custom Properties** — the component's own tokens, always aliased to a `brandsync-tokens` value
+   by default (e.g. `--bs-button-height: var(--bs-scale-500)`), so a consuming app can override just that
+   one property (`bs-button { --bs-button-height: 56px; }`) without touching anything else.
+2. **Shadow Parts** (`::part(name)`) — named internal elements a consumer can target with real CSS
+   (e.g. `::part(icon)`, `::part(label)`). Used when a variable isn't expressive enough (e.g. positioning,
+   pseudo-classes).
+3. **Slots** — named content-injection points (e.g. `slot="icon"`) for consumer-supplied markup.
+
+Every `@Prop` is the fourth, distinct thing: a pre-built configuration option (`variant`, `size`,
+`disabled`, ...) with a fixed, valid set of values — not a customization escape hatch.
+
+If a consuming team needs to change something not covered by one of these four, that's a request back to
+this library to expose a new variable/part/slot — the same request loop as any shared design system
+dependency, not a per-team CSS override.
+
+## Naming
+
+- CSS Custom Properties: `--bs-<component>-<property>[-<state>]`, e.g. `--bs-button-bg-primary-hover`.
+  Always alias to a `brandsync-tokens` variable, never a hardcoded value, so a global token change still
+  cascades even where a component hasn't been touched.
+- Shadow Parts: singular, lowercase, structural noun (`label`, `icon`, `container`, `row`, `cell`) — not
+  state (no `::part(hovered)`).
+- Slots: same naming style as parts; default (unnamed) slot only when there's exactly one sensible content
+  area (e.g. a button's label).
+
+## Non-string props
+
+HTML attributes can only carry strings. Any `@Prop` whose value is an array/object (e.g. `bs-data-table`'s
+`columns`/`rows`) must be set as a JS property, not an attribute, and must be documented as such in the
+MCP's `web_component` corpus entry for that component — this is the one place the "just an HTML tag"
+mental model needs a caveat.
+
+## Composition: every component is built from smaller components
+
+A component's markup is made of other `bs-*` components wherever one already does the job. Hand-written
+elements are for things no existing component covers (a calendar day cell, the pattern of a QR code), not
+for re-drawing a card, a button, an input or a menu. This keeps behaviour, accessibility and theming in one
+place: fix `bs-button` once and every component that contains one is fixed.
+
+**The rule**
+
+1. **Reuse before you write.** Before adding a `<div>` with its own background, border, radius or shadow, a
+   `<button>`, a text field, a menu, a chip, a spinner, a switch or a tile, check whether a `bs-*` component
+   already is that (`bs-card`, `bs-button`, `bs-icon-button`, `bs-input`, `bs-menu`/`bs-menu-item`,
+   `bs-chip-*`, `bs-progress`, `bs-switch`, `bs-icon-tile`, ...) and use it.
+2. **Anything card-shaped is a `bs-card`.** A raised or bordered container that groups content is a
+   `bs-card`, restyled through its custom properties (`--bs-card-radius`, `--bs-card-padding`,
+   `--bs-card-border-width`, `--bs-card-shadow`, `--bs-card-overflow`, ...) -- never a second hand-rolled
+   card surface.
+3. **If the child can't do what you need, change the child.** Add the missing custom property, part or slot
+   to the smaller component (through the normal customization surface above) in its own change, then use it.
+   Don't reach inside with `::part()` to override what the child should expose, don't copy its styles, and
+   don't fork it into a look-alike.
+4. **Configure children through their public surface only**: their `@Prop`s, slots, and custom properties set
+   on the child element (e.g. `.bs-qr-code { --bs-card-border-width: 1px; }`). Alias the parent's own
+   documented variables to the child's, so a consumer still has one place to override
+   (`--bs-card-padding: var(--bs-qr-code-padding)`).
+5. **Name the child element with a part** (`<bs-card part="container">`), so the parent's consumers can still
+   reach it with `::part(container)`.
+6. **Say what you composed.** The component's JSDoc/mdx lists the components it is built from, so a reader
+   knows where its behaviour and tokens really come from.
+
+**What may stay hand-built:** leaf elements with no existing component and no sensible one to add (a day
+cell, a spinner value, a QR matrix, an arrow); icons drawn as inline SVG until the library has an icon
+component; one-off layout wrappers (flex rows and columns that only position children).
+
+**One caveat -- shadows around odd shapes.** A `bs-card` paints its own `box-shadow`. If a component needs
+one shadow around the card *and* something attached to it (like `bs-product-tour`'s pointer arrow), turn the
+card's shadow off (`--bs-card-shadow: none`) and put a `filter: drop-shadow(...)` on a wrapper that holds
+both. The card is still the surface.
+
+**In review:** a PR that adds a component, or a hand-rolled container/button/field inside one, is checked
+against this section. "No existing component fit" needs a reason; the usual answer is a missing custom
+property on the existing one.
+
+
+## Per-tenant brand theming
+
+Override the brand scale `--bs-brand-50` … `--bs-brand-950` on any element carrying a `data-brand`
+attribute. Every brand-derived token (primary default/hover/pressed/container, text/icon action,
+primary border, focus rings) is re-declared on `[data-brand]` in the vendored token stylesheet, so
+the override works anywhere in the tree rather than only on `:root`:
+
+```css
+[data-brand="teal"] { --bs-brand-50: #effdfa; /* ... */ --bs-brand-950: #042f2c; }
+```
+
+```html
+<div data-brand="teal"> ...bs-* components... </div>
+```
+
+Focus rings follow the brand inside a `data-brand` element; outside one they keep the
+information-blue default. Dark mode (`data-theme="dark"`) works on the same element or an ancestor.
+Success/error/warning colours are not part of this contract. Per-component CSS variables, parts
+and slots are listed in `REFERENCE.md`, shipped in the npm package.
+
+## Hiding controls and localising text
+
+Optional built-in controls have `hide*` props that remove them from the DOM (not just visually):
+`bs-composer` (`hideAttach`, `hideMic`), `bs-chatbot-header` (`hideNewChat`, `hideHistory`,
+`hideExpand`, `hideClose`), `bs-chatbot-response-action` (`hideRegenerate`). Every internal
+accessible name / tooltip string is a `*Label` prop whose default is the existing English text.