@usequeek/theme-kit 0.1.22 → 0.1.23

package/README.md

@@ -346,8 +346,10 @@ keeps the page, the query string and the hash.
 ```tsx
 import { LanguageSwitcher } from '@usequeek/theme-kit/components/language-switcher';
 
-<LanguageSwitcher />                        // native <select> (default)
-<LanguageSwitcher variant="inline-list" />  // every language as a link
+<LanguageSwitcher variant="menu" />                  // button + popover (sheet on phones) — recommended
+<LanguageSwitcher variant="menu" side="top" />       // a footer: opens upward
+<LanguageSwitcher variant="inline-list" />           // every language as a link (footer, up to four)
+<LanguageSwitcher />                                 // native <select> — legacy
 ```
 
 Place it unconditionally, in the header or the footer: it renders nothing on a
@@ -357,10 +359,114 @@ store's languages.
 | Prop | Default | |
 | --- | --- | --- |
 | `className` | | Extra class on the root, to position or restyle it. |
-| `variant` | `'select'` | `'select'`: one native dropdown (best keyboard, touch and screen-reader behaviour). `'inline-list'`: a link per language that wraps on narrow screens; suits a footer. |
+| `variant` | `'select'` | `'menu'`: a trigger button and a list of language links (below). `'inline-list'`: a link per language that wraps on narrow screens. `'select'`: one native dropdown, **legacy** — it works and is unchanged, but its open list is the operating system's menu and cannot be styled; prefer `menu`. |
+| `side` | `'bottom'` | `menu` only. `'top'` opens above the trigger, for footers. Flips by itself when the preferred side does not fit. |
+| `align` | `'end'` | `menu` only. Line the popover up with the trigger's inline `'end'` or `'start'` edge (mirrors in right-to-left). Flips and shifts to stay inside the viewport. |
 | `showNativeName` | `true` | Label languages in their own language (`Français`) instead of English (`French`). |
-| `showCode` | `false` | Append the code: `Français · FR`. |
-| `children` | | Render-prop `(state) => ReactNode`: replaces the default control entirely (never called on a single-language store). `state` is `useLocales()` plus `label`, `labelFor(locale)` and `displayName(locale)`. |
+| `showCode` | `false` | Show the language code (`FR`) next to the name. |
+| `children` | | Render-prop `(state) => ReactNode`: replaces the default control entirely (never called on a single-language store). `state` is `useLocales()` plus `label`, `labelFor(locale)`, `displayName(locale)`, `open` and `setOpen`. |
+
+### The `menu` variant
+
+A real `<button>` opens a list of language **links** (`<a href>` built from the
+current page, so open-in-new-tab and copy-link work). On screens wider than
+640px it is a popover under the trigger; below 640px it becomes a bottom sheet
+with a scrim, safe-area padding, and page scroll locked while it is open. The
+wide/narrow layout switch is CSS only (one media query), so the markup is the
+same on both and server and client agree; JavaScript only consults the media
+query while the menu opens, to lock scroll and to place the popover.
+With more than four languages in a footer, use `menu` with `side="top"` rather
+than `inline-list`. 2 to 20 languages are fine: the list scrolls past about
+eight rows, and a long list can use two columns on wide screens (below).
+
+It is the *disclosure* pattern, not a listbox, because choosing an item
+navigates: the button has `aria-expanded` and `aria-controls` and the name
+"Language: English"; the list is a `<ul>` labelled by its title; the current
+language's link has `aria-current="true"`; there are no `option` roles.
+
+| Key | |
+| --- | --- |
+| Enter, Space, ArrowDown on the button | Open, focus on the current language |
+| ArrowUp on the button | Open, focus on the last language |
+| ArrowDown / ArrowUp in the list | Next / previous link (wraps) |
+| Home / End | First / last link |
+| Typing letters | Jump to the language whose name or code starts with them (500 ms buffer) |
+| Enter on a link | Follow it (native); Space does the same |
+| Escape | Close and return focus to the button |
+| Tab | Close the menu |
+| Click outside, scrim tap | Close |
+
+Only the focused link is in the tab order (roving tabindex), so Tab leaves the
+list and closes it. Choosing a language closes the menu, returns focus to the
+button and navigates (a modified click — new tab, copy link — is left to the
+browser). Motion respects `prefers-reduced-motion` (an 80 ms fade only).
+
+**Styling surface.** Every part has a class and a `data-part` attribute; the
+root also carries state attributes:
+
+| Part | Class | `data-part` |
+| --- | --- | --- |
+| Root | `qn-lang qn-lang--menu` | `data-qn-language-switcher`, `data-variant="menu"` |
+| Trigger button | `qn-lang__trigger` | `trigger` |
+| Trigger name / code / chevron | `qn-lang__trigger-label` / `__trigger-code` / `__chevron` | `trigger-label` / `trigger-code` / `chevron` |
+| Scrim (sheet) | `qn-lang__scrim` | `scrim` |
+| Popover / sheet | `qn-lang__popover` | `popover` |
+| Sheet grabber | `qn-lang__handle` | `handle` |
+| Group label | `qn-lang__title` | `title` |
+| List / item | `qn-lang__options` / `__item` | `list` / `item` |
+| Link (current: `aria-current="true"`, `data-current="true"`) | `qn-lang__option` | `option` |
+| Name / code / current marker | `qn-lang__name` / `__code` / `__mark` | `name` / `code` / `mark` |
+
+Root attributes: `data-state="open|closed"`, `data-side="bottom|top"`,
+`data-align="start|end"`, `data-mode="popover|sheet"` (while open),
+`data-count="<n>"`, `data-many="true"` (more than ten languages),
+`data-show-code="true"`. The code spans are always rendered and hidden by
+default, so a theme can show a code-only trigger with
+`.my-header [data-part='trigger-label'] { display: none }` plus
+`.my-header [data-part='trigger-code'] { display: inline }`.
+
+| Variable | Default | Controls |
+| --- | --- | --- |
+| `--qn-lang-surface` | `--qn-surface` | popover / sheet background |
+| `--qn-lang-ink` | `--qn-text` | text colour |
+| `--qn-lang-muted` | `--qn-text-muted` | title and code colour |
+| `--qn-lang-border` | `--qn-border` | hairlines |
+| `--qn-lang-radius` | `--qn-radius-md` (8px) | trigger / popover corners |
+| `--qn-lang-item-radius` | `--qn-radius-sm` (6px) | link corners |
+| `--qn-lang-item-hover` / `--qn-lang-current-bg` | 6% ink / none | hover and current-link backgrounds |
+| `--qn-lang-accent` | `--qn-accent` | current marker colour |
+| `--qn-lang-focus` | `--qn-focus` | focus ring |
+| `--qn-lang-shadow` | subtle | popover shadow |
+| `--qn-lang-row-height` / `--qn-lang-sheet-row-height` | 44px / 52px | link height (popover / sheet) |
+| `--qn-lang-gap` / `--qn-lang-pad` | 0 / 4px | space between links / inside the popover |
+| `--qn-lang-offset` | 8px | gap between trigger and popover |
+| `--qn-lang-popover-width` | 240px | popover width |
+| `--qn-lang-many-width` / `--qn-lang-many-columns` | popover width / 1 | width and columns when `data-many="true"` (set `--qn-lang-many-columns: 2` and a wider width for two columns) |
+| `--qn-lang-list-max` | 8.5 rows | height at which the list scrolls |
+| `--qn-lang-sheet-radius` | 16px | sheet top corners |
+| `--qn-lang-scrim` | 40% black | scrim colour |
+| `--qn-lang-z` | 50 | z-index |
+| `--qn-lang-duration` / `--qn-lang-ease` | 160ms / ease-out curve | open motion |
+
+Each variable falls back to the matching `--qn-*` token, then a neutral
+value, and is never set by the kit itself — set it on the root, on an
+ancestor, or on `:root`. The sheet breakpoint (640px) is fixed.
+
+Restyling recipe — no override of internals needed:
+
+```css
+.site-header [data-qn-language-switcher] {
+  --qn-lang-surface: #f3f0e9;
+  --qn-lang-ink: #1b2029;
+  --qn-lang-radius: 0;
+  --qn-lang-item-radius: 0;
+  --qn-lang-popover-width: 280px;
+  --qn-lang-sheet-radius: 0;
+  --qn-lang-duration: 120ms;
+}
+.site-header [data-part='trigger'] { border: 0; letter-spacing: 0.12em; text-transform: uppercase; }
+.site-header [data-part='option'][aria-current='true'] { font-style: italic; }
+```
 
 **Tell the storefront the theme places it.** Set `languageSwitcher: 'theme'` in
 the theme manifest. Without it the storefront keeps rendering its own floating

package/components/language-menu.css

@@ -0,0 +1,349 @@
+/* ============================================================
+   LanguageSwitcher variant="menu" — a trigger and a list of language links:
+   a popover on wide screens, a bottom sheet below 640px. Prefix: qn-lang.
+
+   STYLING SURFACE. Every part has a class AND a data-part attribute:
+     root            .qn-lang--menu [data-qn-language-switcher][data-variant="menu"]
+     trigger         .qn-lang__trigger          [data-part="trigger"]
+       label/code    .qn-lang__trigger-label    [data-part="trigger-label"]
+                     .qn-lang__trigger-code     [data-part="trigger-code"]
+       chevron       .qn-lang__chevron          [data-part="chevron"]
+     scrim           .qn-lang__scrim            [data-part="scrim"]
+     popover/sheet   .qn-lang__popover          [data-part="popover"]
+       grabber       .qn-lang__handle           [data-part="handle"]
+       group label   .qn-lang__title            [data-part="title"]
+       list          .qn-lang__options          [data-part="list"]
+       item          .qn-lang__item             [data-part="item"]
+       link          .qn-lang__option           [data-part="option"]  (aria-current / data-current on the current one)
+         name/code   .qn-lang__name / __code    [data-part="name"] / [data-part="code"]
+         marker      .qn-lang__mark             [data-part="mark"]
+   State on the root: data-state="open|closed", data-side="bottom|top",
+   data-align="start|end", data-mode="popover|sheet" (while open),
+   data-count="<n>", data-many="true" (more than 10), data-show-code="true".
+
+   VARIABLES (--qn-lang-*): each is read as var(--qn-lang-x, var(--qn-token, fallback)),
+   and none is declared on the root, so set them on the root, an ancestor or :root.
+     surface ink muted border radius item-radius item-hover current-bg accent
+     focus shadow row-height sheet-row-height gap pad offset popover-width
+     many-width many-columns list-max sheet-radius scrim z duration ease
+   Logical properties only: it mirrors itself in right-to-left storefronts.
+   ============================================================ */
+
+.qn-lang--menu {
+  position: relative;
+  display: inline-block;
+  max-inline-size: 100%;
+}
+
+/* ── trigger ───────────────────────────────────────────── */
+
+.qn-lang__trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  min-inline-size: 44px;
+  min-block-size: 44px;
+  padding-inline: 12px;
+  border: 1px solid var(--qn-lang-border, var(--qn-border, color-mix(in srgb, currentColor 22%, transparent)));
+  border-radius: var(--qn-lang-radius, var(--qn-radius-sm, 6px));
+  background: transparent;
+  color: var(--qn-lang-ink, var(--qn-text, inherit));
+  font: inherit;
+  line-height: 1.25;
+  white-space: nowrap;
+  cursor: pointer;
+}
+
+.qn-lang__trigger:hover {
+  border-color: var(--qn-lang-ink, var(--qn-text, currentColor));
+}
+
+.qn-lang__trigger:focus-visible,
+.qn-lang__option:focus-visible {
+  outline: 2px solid var(--qn-lang-focus, var(--qn-focus, currentColor));
+  outline-offset: 2px;
+}
+
+.qn-lang__trigger-code,
+.qn-lang__code {
+  display: none;
+  color: var(--qn-lang-muted, var(--qn-text-muted, color-mix(in srgb, currentColor 60%, transparent)));
+  font-size: 0.8em;
+  letter-spacing: 0.04em;
+}
+
+.qn-lang--menu[data-show-code='true'] .qn-lang__trigger-code,
+.qn-lang--menu[data-show-code='true'] .qn-lang__code {
+  display: inline;
+}
+
+.qn-lang__trigger .qn-lang__chevron {
+  position: static;
+  inline-size: 10px;
+  block-size: 10px;
+  flex: none;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.8;
+}
+
+/* ── popover ───────────────────────────────────────────── */
+
+.qn-lang__popover {
+  position: absolute;
+  z-index: var(--qn-lang-z, 50);
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  inline-size: var(--qn-lang-popover-width, 240px);
+  max-inline-size: calc(100vw - 32px);
+  max-block-size: var(--qn-lang-avail, none);
+  padding: var(--qn-lang-pad, 4px);
+  overflow: hidden;
+  border: 1px solid var(--qn-lang-border, var(--qn-border, color-mix(in srgb, currentColor 16%, transparent)));
+  border-radius: var(--qn-lang-radius, var(--qn-radius-md, 8px));
+  background: var(--qn-lang-surface, var(--qn-surface, Canvas));
+  color: var(--qn-lang-ink, var(--qn-text, CanvasText));
+  box-shadow: var(--qn-lang-shadow, 0 4px 16px rgb(0 0 0 / 0.08));
+  font: inherit;
+  text-align: start;
+  translate: var(--qn-lang-shift, 0px) 0;
+}
+
+.qn-lang__popover[hidden],
+.qn-lang__scrim[hidden] {
+  display: none;
+}
+
+.qn-lang--menu[data-side='bottom'] > .qn-lang__popover {
+  inset-block-start: calc(100% + var(--qn-lang-offset, 8px));
+}
+
+.qn-lang--menu[data-side='top'] > .qn-lang__popover {
+  inset-block-end: calc(100% + var(--qn-lang-offset, 8px));
+}
+
+.qn-lang--menu[data-align='end'] > .qn-lang__popover {
+  inset-inline-end: 0;
+}
+
+.qn-lang--menu[data-align='start'] > .qn-lang__popover {
+  inset-inline-start: 0;
+}
+
+.qn-lang--menu[data-many='true'] > .qn-lang__popover {
+  inline-size: var(--qn-lang-many-width, var(--qn-lang-popover-width, 240px));
+}
+
+.qn-lang__handle,
+.qn-lang__scrim {
+  display: none;
+}
+
+.qn-lang__title {
+  padding: 8px 12px 6px;
+  color: var(--qn-lang-muted, var(--qn-text-muted, color-mix(in srgb, currentColor 60%, transparent)));
+  font-size: 0.75em;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+/* ── list ──────────────────────────────────────────────── */
+
+.qn-lang__options {
+  display: grid;
+  grid-template-columns: repeat(var(--qn-lang-many-columns, 1), minmax(0, 1fr));
+  gap: var(--qn-lang-gap, 0);
+  flex: 1 1 auto;
+  min-block-size: 0;
+  max-block-size: var(--qn-lang-list-max, calc(var(--qn-lang-row-height, 44px) * 8.5));
+  margin: 0;
+  padding: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  list-style: none;
+}
+
+/* The extra columns only apply to long lists. */
+.qn-lang--menu:not([data-many='true']) .qn-lang__options {
+  grid-template-columns: minmax(0, 1fr);
+}
+
+.qn-lang__item {
+  display: block;
+  margin: 0;
+  padding: 0;
+}
+
+.qn-lang__option {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  box-sizing: border-box;
+  min-block-size: var(--qn-lang-row-height, 44px);
+  padding-inline: 12px;
+  border-radius: var(--qn-lang-item-radius, var(--qn-radius-sm, 6px));
+  color: inherit;
+  font: inherit;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.qn-lang__option:hover {
+  background: var(--qn-lang-item-hover, color-mix(in srgb, currentColor 6%, transparent));
+}
+
+.qn-lang__option[aria-current='true'] {
+  background: var(--qn-lang-current-bg, transparent);
+  font-weight: 600;
+}
+
+.qn-lang__option:focus-visible {
+  outline-offset: -2px;
+}
+
+.qn-lang__name {
+  flex: 1 1 auto;
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.qn-lang__code {
+  flex: none;
+}
+
+.qn-lang__mark {
+  display: inline-flex;
+  inline-size: 16px;
+  block-size: 16px;
+  flex: none;
+  color: var(--qn-lang-accent, var(--qn-accent, currentColor));
+  visibility: hidden;
+}
+
+.qn-lang__option[aria-current='true'] .qn-lang__mark {
+  visibility: visible;
+}
+
+.qn-lang__mark svg {
+  inline-size: 100%;
+  block-size: 100%;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 1.8;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+/* ── motion ────────────────────────────────────────────── */
+
+@keyframes qn-lang-pop-down {
+  from { opacity: 0; transform: translateY(-4px); }
+  to { opacity: 1; transform: none; }
+}
+
+@keyframes qn-lang-pop-up {
+  from { opacity: 0; transform: translateY(4px); }
+  to { opacity: 1; transform: none; }
+}
+
+@keyframes qn-lang-sheet-in {
+  from { transform: translateY(100%); }
+  to { transform: none; }
+}
+
+@keyframes qn-lang-fade-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.qn-lang--menu[data-side='bottom'] > .qn-lang__popover:not([hidden]) {
+  animation: qn-lang-pop-down var(--qn-lang-duration, 160ms) var(--qn-lang-ease, cubic-bezier(0.2, 0.8, 0.2, 1));
+}
+
+.qn-lang--menu[data-side='top'] > .qn-lang__popover:not([hidden]) {
+  animation: qn-lang-pop-up var(--qn-lang-duration, 160ms) var(--qn-lang-ease, cubic-bezier(0.2, 0.8, 0.2, 1));
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .qn-lang__chevron {
+    transition: rotate var(--qn-lang-duration, 160ms) var(--qn-lang-ease, ease);
+  }
+}
+
+.qn-lang--menu[data-state='open'] .qn-lang__trigger .qn-lang__chevron {
+  rotate: 180deg;
+}
+
+/* ── bottom sheet (narrow screens) ─────────────────────── */
+
+@media (max-width: 639.98px) {
+  .qn-lang__scrim:not([hidden]) {
+    position: fixed;
+    inset: 0;
+    z-index: calc(var(--qn-lang-z, 50) - 1);
+    display: block;
+    background: var(--qn-lang-scrim, rgb(0 0 0 / 0.4));
+    animation: qn-lang-fade-in var(--qn-lang-duration, 160ms) linear;
+  }
+
+  /* [data-side][data-align] outranks the popover placement rules above. */
+  .qn-lang--menu[data-side][data-align] > .qn-lang__popover {
+    position: fixed;
+    inset-block: auto 0;
+    inset-inline: 0;
+    inline-size: auto;
+    max-inline-size: none;
+    max-block-size: 85vh;
+    max-block-size: 85dvh;
+    padding: var(--qn-lang-pad, 4px) var(--qn-lang-pad, 4px) calc(var(--qn-lang-pad, 4px) + env(safe-area-inset-bottom, 0px));
+    border-inline-width: 0;
+    border-block-end-width: 0;
+    border-start-start-radius: var(--qn-lang-sheet-radius, 16px);
+    border-start-end-radius: var(--qn-lang-sheet-radius, 16px);
+    border-end-start-radius: 0;
+    border-end-end-radius: 0;
+    translate: none;
+  }
+
+  .qn-lang--menu[data-side][data-align] > .qn-lang__popover:not([hidden]) {
+    animation: qn-lang-sheet-in calc(var(--qn-lang-duration, 160ms) * 1.5) var(--qn-lang-ease, cubic-bezier(0.2, 0.8, 0.2, 1));
+  }
+
+  .qn-lang__handle {
+    display: block;
+    inline-size: 36px;
+    block-size: 4px;
+    margin: 8px auto 4px;
+    border-radius: 2px;
+    background: color-mix(in srgb, currentColor 25%, transparent);
+  }
+
+  .qn-lang--menu .qn-lang__options,
+  .qn-lang--menu:not([data-many='true']) .qn-lang__options {
+    grid-template-columns: minmax(0, 1fr);
+    max-block-size: none;
+  }
+
+  .qn-lang__option {
+    min-block-size: var(--qn-lang-sheet-row-height, 52px);
+  }
+}
+
+/* Page scroll is locked behind an open sheet. */
+body.qn-lang-lock {
+  overflow: hidden;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .qn-lang--menu[data-side][data-align] > .qn-lang__popover:not([hidden]) {
+    animation: qn-lang-fade-in 80ms linear;
+  }
+
+  .qn-lang__scrim:not([hidden]) {
+    animation-duration: 80ms;
+  }
+}