@plitzi/sdk-server 0.37.8 → 0.37.10

package/skills/plitzi-authoring/recipes/marquee.ts

@@ -0,0 +1,57 @@
+/**
+ * A marquee: a row of names that scrolls for ever and stops under the pointer. The items are rendered three times
+ * and the keyframe moves the track by a third, so the end meets the start with no jump.
+ */
+import { apiContainer, container, list, styles, text } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+const marquee = styles('marquee', { overflow: 'hidden' });
+
+const track = styles('marquee-track', {
+  css: {
+    display: 'flex',
+    gap: '48px',
+    width: 'max-content',
+    margin: '0px',
+    padding: '0px',
+    'list-style-type': 'none',
+    animation: 'marquee 30s linear infinite'
+  },
+  // An ancestor's state reaches inside it: hovering the band pauses the track.
+  ancestors: { [marquee.name]: { states: { hover: { 'animation-play-state': 'paused' } } } }
+});
+
+export const recipe: SpaceSpec = {
+  name: 'Marquee',
+  permanentUrl: 'marquee',
+  customCss: '@keyframes marquee { to { transform: translateX(calc(-100% / 3)); } }',
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        apiContainer({
+          id: 'catalog',
+          query: '/data/brands.json',
+          cache: true,
+          children: [
+            container({
+              class: marquee,
+              children: [
+                list({
+                  id: 'brands',
+                  class: track,
+                  from: 'catalog.data.brands',
+                  as: '{{ source|merge(source)|merge(source) }}',
+                  children: [text({ from: 'brands.item' })]
+                })
+              ]
+            })
+          ]
+        })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/plugin.ts

@@ -0,0 +1,53 @@
+/**
+ * An element of your own (a plugin): authored from its declaration — the one `plitzi add plugin` writes — so a flow on
+ * its events, a step to its actions and its attributes are all checked. Hand the declaration to `authorSpace` too.
+ */
+import {
+  button,
+  declaredCallback,
+  declaredTrigger,
+  defineElement,
+  named,
+  onClick,
+  setState
+} from '@plitzi/sdk-authoring';
+
+import type { PluginDeclarationData, SpaceSpec } from '@plitzi/sdk-authoring';
+
+// In a project: `import declaration from './plugins/seatPicker/declaration';`
+const declaration = {
+  type: 'seatPicker',
+  triggers: { onPick: { action: 'onPick', title: 'On Pick', type: 'trigger', params: {}, preview: { seat: '' } } },
+  callbacks: { reset: { action: 'reset', title: 'Reset', type: 'callback', params: {} } },
+  content: { attributes: { rows: 10 }, definition: { label: 'Seat Picker' } }
+} as const;
+
+const seatPicker = defineElement<{ rows?: number }>(declaration);
+
+// `authorSpace(recipe, { plugins })` — in a project, `src/plugins/declarations.ts` lists them all.
+export const plugins: PluginDeclarationData[] = [declaration];
+
+export const recipe: SpaceSpec = {
+  name: 'Seats',
+  permanentUrl: 'seats',
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        seatPicker({
+          id: 'seats',
+          rows: 12,
+          flows: [
+            [
+              named('picked', declaredTrigger(declaration, 'onPick')),
+              setState({ key: 'seat', type: 'text', value: '{{ picked.seat }}' })
+            ]
+          ]
+        }),
+        button({ content: 'Clear', flows: [[onClick(), declaredCallback(declaration, 'reset', { on: 'seats' })]] })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/scroll-a-row.ts

@@ -0,0 +1,79 @@
+/**
+ * A row that scrolls sideways — swiped on a phone, moved by arrows elsewhere: the row's box scrolls
+ * (`overflow-x: auto`), the arrows move it by most of what it shows, and `onScroll` hides each arrow at its end.
+ */
+import {
+  button,
+  container,
+  list,
+  named,
+  onClick,
+  onScroll,
+  scrollBy,
+  setState,
+  styles,
+  text
+} from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+const row = styles('card-row', {
+  display: 'flex',
+  gap: '16px',
+  'overflow-x': 'auto',
+  // Stops on a card, never between two.
+  'scroll-snap-type': 'x mandatory',
+  margin: '0px',
+  padding: '0px',
+  'list-style-type': 'none'
+});
+
+const card = styles('row-card', { 'flex-shrink': '0', width: '240px', padding: '16px', 'scroll-snap-align': 'start' });
+
+const CATEGORIES = ['Processors', 'Graphics cards', 'Memory', 'Storage', 'Monitors', 'Keyboards', 'Mice', 'Cases'];
+
+export const recipe: SpaceSpec = {
+  name: 'Row',
+  permanentUrl: 'row',
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        container({
+          children: [
+            // Shown until the row says it is at that end: the arrows are there before anybody scrolls.
+            button({
+              content: '',
+              title: 'Previous categories',
+              visible: '!state.rowAtStart',
+              children: [text('‹')],
+              flows: [[onClick(), scrollBy('categories', { x: '-80%' })]]
+            }),
+            list({
+              id: 'categories',
+              class: row,
+              items: CATEGORIES,
+              flows: [
+                [
+                  named('moved', onScroll()),
+                  setState({ key: 'rowAtStart', type: 'boolean', value: '{{ moved.atStart }}' }),
+                  setState({ key: 'rowAtEnd', type: 'boolean', value: '{{ moved.atEnd }}' })
+                ]
+              ],
+              children: [text({ class: card, from: 'categories.item' })]
+            }),
+            button({
+              content: '',
+              title: 'More categories',
+              visible: '!state.rowAtEnd',
+              children: [text('›')],
+              flows: [[onClick(), scrollBy('categories', { x: '80%' })]]
+            })
+          ]
+        })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/show-data.ts

@@ -0,0 +1,73 @@
+/* eslint-disable quotes -- templates quote their own strings, and read best in the other quotes */
+/**
+ * Show data with no backend: a JSON file the project serves (`public/data/products.json`), read by a provider — one
+ * card per product, a skeleton while it loads, a count, a computed value, and an empty state that never flashes.
+ */
+import { apiContainer, container, heading, list, styles, text } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+// A list is a `<ul>`: a grid of cards takes the bullets and the indent off.
+const grid = styles('product-grid', {
+  display: 'grid',
+  'grid-template-columns': 'repeat(auto-fill, minmax(220px, 1fr))',
+  gap: '16px',
+  margin: '0px',
+  padding: '0px',
+  'list-style-type': 'none'
+});
+
+const card = styles('product-card', { padding: '16px', 'border-radius': '12px', 'background-color': 'var(--card)' });
+
+// The shape of what is coming, shown until the file answers.
+const skeleton = styles('product-skeleton', {
+  height: '96px',
+  'border-radius': '12px',
+  'background-color': 'var(--card)'
+});
+
+export const recipe: SpaceSpec = {
+  name: 'Catalogue',
+  permanentUrl: 'catalogue',
+  variables: { color: { card: { light: '#ffffff', dark: '#16161d', default: '#ffffff' } } },
+  // Read anywhere as `computed.cartCount`, declared once.
+  computed: { cartCount: '{{ (state.cart ?? [])|length }}' },
+  // How a price is shown, said once: `text({ from: …, as: 'price' })` anywhere.
+  formats: { price: "{{ source|currency('USD', 'en', { trimZeros: true }) }}" },
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        text({ from: 'computed.cartCount', as: '{{ source }} in the cart' }),
+        apiContainer({
+          id: 'catalog',
+          query: '/data/products.json',
+          cache: true,
+          // Shown in place of the rest until the first answer, and gone after it.
+          loadingSlot: 'catalog-skeleton',
+          children: [
+            container({ id: 'catalog-skeleton', class: skeleton }),
+            // Inside a template a source is spelled in full; a binding's own source is `source`.
+            text({ from: 'catalog.data.products', as: '{{ source|length }} products' }),
+            list({
+              id: 'products',
+              class: grid,
+              items: 'catalog.data.products',
+              children: [
+                // Inside a row, a binding names the row short (`products.item`), a template in full (`list_products`).
+                heading({ subType: 'h3', class: card, from: 'products.item.title' }),
+                text({ from: 'products.item.price', as: 'price' })
+              ]
+            }),
+            // Revealed by the data, so it starts hidden: nothing flashes while the file loads.
+            text('No products yet.', {
+              visible: { source: 'catalog.data.products', template: '{{ source is defined and source|length == 0 }}' }
+            })
+          ]
+        })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/style-a-page.ts

@@ -0,0 +1,45 @@
+/**
+ * Style without copies: colours are tokens with a light and a dark value, a look used twice is a class, "this class
+ * plus one thing" is rules on top of it (`class: [card, { … }]`, which needs an `id`), and a rule for tablet AND phone
+ * is written once under `compact`.
+ */
+import { container, heading, styles, text } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+const card = styles('card', {
+  css: {
+    desktop: { display: 'flex', 'flex-direction': 'column', gap: '8px', padding: '24px', 'border-radius': '16px' },
+    // Tablet (48–64rem) and mobile (below 48rem) each inherit from desktop alone: `compact` is both.
+    compact: { padding: '16px' }
+  },
+  states: { hover: { 'border-color': 'var(--primary)' } }
+});
+
+export const recipe: SpaceSpec = {
+  name: 'Styled',
+  permanentUrl: 'styled',
+  variables: {
+    color: {
+      foreground: { light: '#0c0c14', dark: '#ededf3', default: '#0c0c14' },
+      card: { light: '#ffffff', dark: '#101019', default: '#ffffff' },
+      primary: { light: '#4f46e5', dark: '#818cf8', default: '#4f46e5' }
+    }
+  },
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      css: { 'background-color': 'var(--card)', color: 'var(--foreground)', padding: '48px 24px' },
+      body: [
+        container({ class: card, children: [heading('Plain', { subType: 'h2' }), text('The class as it is.')] }),
+        container({
+          id: 'featured',
+          class: [card, { 'border-width': '2px', 'border-style': 'solid', 'border-color': 'var(--primary)' }],
+          children: [heading('Featured', { subType: 'h2' }), text('The class, plus one thing.')]
+        })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/typed-data.ts

@@ -0,0 +1,64 @@
+/* eslint-disable quotes -- templates quote their own strings, and read best in the other quotes */
+/**
+ * Data typed by a sample of it: `source()` turns the JSON the page reads into names the editor completes and checks —
+ * `site.data.hero.titel` is a type error, not an empty heading. In a project the sample is the file itself:
+ * `import home from '../../public/data/home.json' with { type: 'json' }`.
+ */
+import { apiContainer, heading, list, source, styles, text, twig } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+const home = {
+  hero: { title: 'Fresh this week', subtitle: 'Picked by the team' },
+  products: [
+    { title: 'Desk lamp', price: 49 },
+    { title: 'Notebook', price: 12, badge: 'new' }
+  ]
+};
+
+const site = source('site', home);
+
+const grid = styles('typed-grid', {
+  display: 'grid',
+  gap: '12px',
+  margin: '0px',
+  padding: '0px',
+  listStyleType: 'none'
+});
+
+export const recipe: SpaceSpec = {
+  name: 'Typed data',
+  permanentUrl: 'typed-data',
+  formats: { price: "{{ source|currency('USD', 'en') }}" },
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        apiContainer({
+          id: site.id,
+          query: '/data/home.json',
+          cache: true,
+          children: [
+            heading({ from: site.data.hero.title }),
+            text({ from: site.data.hero.subtitle }),
+            // A template takes the paths through `twig`, each written in full.
+            text({ content: twig`{{ ${site.data.products}|length }} products` }),
+            list({
+              id: 'products',
+              class: grid,
+              items: site.data.products,
+              // The row's item is typed as the sample's: every field any product has.
+              row: product => [
+                text({ from: product.item.title }),
+                text({ from: product.item.price, as: 'price' }),
+                text({ from: product.item.badge, visible: product.item.badge })
+              ]
+            })
+          ]
+        })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/usable-without-sight.ts

@@ -0,0 +1,39 @@
+/**
+ * Controls a screen reader and a browser agent can use: an icon-only button says what it does, a clickable card IS a
+ * button, a field keeps its label out of sight rather than dropping it, a picture says what it shows or that it only
+ * decorates.
+ */
+import { button, fontAwesome, formControl, image, setState, styles, text, onClick } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+const card = styles('plan-card', {
+  display: 'flex',
+  'flex-direction': 'column',
+  padding: '16px',
+  'text-align': 'left'
+});
+
+export const recipe: SpaceSpec = {
+  name: 'Accessible',
+  permanentUrl: 'accessible',
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        button({ content: '', title: 'Search', children: [fontAwesome({ icon: 'fa-solid fa-magnifying-glass' })] }),
+        button({
+          content: '',
+          class: card,
+          children: [text('Pro'), text('12 € a month')],
+          flows: [[onClick(), setState({ key: 'plan', type: 'text', value: 'pro' })]]
+        }),
+        formControl({ name: 'q', label: 'Search the docs', hideLabel: true, placeholder: 'Search…' }),
+        image({ src: '/team.jpg', alt: 'The team at the 2026 offsite' }),
+        image({ src: '/grain.png', decorative: true })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/reference/accessibility.md

@@ -19,7 +19,7 @@ button({ content: '', title: 'Close', children: [fontAwesome({ icon: 'fa-solid f
 button({ content: '', label: 'Select (V)', title: 'Select — V', children: [fontAwesome({ icon: 'fa-solid fa-arrow-pointer' }), text('V')] })
 
 // A link around a whole card: without `label` it is announced as every word inside the card.
-link({ href: '/posts/field-notes', mode: 'internal', label: 'Read “Field notes”', children: [ /* cover, topic, title, byline */ ] })
+link({ href: '/posts/field-notes', label: 'Read “Field notes”', children: [ /* cover, topic, title, byline */ ] })
 
 // A field whose design says what it is: the label stays, out of sight.
 formControl({ name: 'q', label: 'Search the docs', hideLabel: true, placeholder: 'Search…' })
@@ -100,7 +100,7 @@ toggle's pressed option.
 
 Anything drawn on a canvas is one picture to these readers. Render what it shows as elements too: a list with a
 named button per action. Keep that list visible when someone asks for it, because an agent clicks by position and
-can't click something that only appears on focus. See `docs/en/accessibility.md` and Pizarra's List view.
+can't click something that only appears on focus.
 
 ## Checking