@plitzi/sdk-server 0.37.9 → 0.38.1

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

@@ -0,0 +1,114 @@
+/**
+ * Three carousels from one element: slides that change on their own with arrows and dots, a marquee of logos that
+ * never ends, and a row of cards a visitor swipes. The slides, the dots and anything else inside read the carousel's
+ * source — `carousel_<id>.index`, `.count`, `.item`, `.items` — and the arrows and dots are steps on it.
+ */
+import {
+  activeWhen,
+  bindTemplate,
+  button,
+  carousel,
+  carouselGoTo,
+  carouselNext,
+  carouselPrevious,
+  container,
+  heading,
+  list,
+  onClick,
+  styles,
+  text
+} from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+const SLIDES = [
+  { id: 'one', title: 'Lamps', lede: 'Warm light for long evenings' },
+  { id: 'two', title: 'Paper', lede: 'Notebooks that lie flat' },
+  { id: 'three', title: 'Pens', lede: 'Six colours, quick to dry' }
+];
+
+const slide = styles('hero-slide', { padding: '64px 32px', backgroundColor: 'var(--card)', borderRadius: '16px' });
+
+const dot = styles('hero-dot', {
+  css: { width: 10, height: 10, padding: '0px', borderRadius: '999px', backgroundColor: 'var(--muted)' },
+  variants: { active: { backgroundColor: 'var(--primary)' } }
+});
+
+const dots = styles('hero-dots', { display: 'flex', gap: 8, margin: '0px', padding: '0px', listStyleType: 'none' });
+
+// Several slides at once: the carousel's class says how wide each is and the gap between them.
+const cards = styles('picks-row', { '--plitzi-carousel-slide-width': '240px', '--plitzi-carousel-gap': '16px' });
+
+export const recipe: SpaceSpec = {
+  name: 'Carousels',
+  permanentUrl: 'carousels',
+  variables: {
+    color: {
+      card: { light: '#f4f4f8', dark: '#1c1c22', default: '#f4f4f8' },
+      muted: { light: '#c4c4cc', dark: '#3a3a44', default: '#c4c4cc' },
+      primary: { light: '#4f46e5', dark: '#818cf8', default: '#4f46e5' }
+    }
+  },
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        // One slide at a time, on its own every 5 s — held while the pointer or the keyboard is on it.
+        carousel({
+          id: 'hero',
+          label: 'Featured',
+          items: SLIDES,
+          autoplay: 5000,
+          row: r =>
+            container({
+              class: slide,
+              children: [heading({ subType: 'h2', from: `${r.item}.title` }), text({ from: `${r.item}.lede` })]
+            }),
+          children: [
+            button({ content: '‹', title: 'Previous slide', flows: [[onClick(), carouselPrevious('hero')]] }),
+            button({ content: '›', title: 'Next slide', flows: [[onClick(), carouselNext('hero')]] }),
+            list({
+              id: 'hero-dots',
+              class: dots,
+              items: 'hero.items',
+              row: r =>
+                button({
+                  content: '',
+                  class: dot,
+                  bind: [
+                    bindTemplate('title', r.index, 'Slide {{ source + 1 }}'),
+                    activeWhen(dot, `{{ ${r.inTemplate.index} == carousel_hero.index }}`)
+                  ],
+                  flows: [[onClick(), carouselGoTo('hero', `{{ ${r.inTemplate.index} }}`)]]
+                })
+            })
+          ]
+        }),
+        // Scrolling past for ever at 40 px a second, still under the pointer.
+        carousel({
+          id: 'logos',
+          label: 'Brands we carry',
+          mode: 'marquee',
+          speed: 40,
+          items: ['Acme', 'Globex', 'Initech', 'Umbrella', 'Hooli'],
+          row: r => text({ from: r.item, css: { padding: '0px 24px', fontWeight: 600 } })
+        }),
+        // A row that swipes on a phone and snaps to each card; the arrows move it a card at a time.
+        carousel({
+          id: 'picks',
+          label: 'Picks',
+          mode: 'scroll',
+          class: cards,
+          items: SLIDES,
+          row: r => container({ class: slide, children: [text({ from: `${r.item}.title` })] }),
+          children: [
+            button({ content: '›', title: 'More picks', flows: [[onClick(), carouselNext('picks')]] }),
+            text({ from: 'picks.index', as: '{{ source + 1 }} of {{ carousel_picks.count }}' })
+          ]
+        })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/detail-page.ts

@@ -0,0 +1,70 @@
+/* eslint-disable quotes -- templates quote their own strings, and read best in the other quotes */
+/**
+ * A page per record: a card links to `/products/<slug>`, and the detail page narrows the same file to the product its
+ * address names — with a message, not an empty page, when no product has that name.
+ */
+import { apiContainer, heading, link, list, text } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+export const recipe: SpaceSpec = {
+  name: 'Detail',
+  permanentUrl: 'detail',
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        apiContainer({
+          id: 'catalog',
+          query: '/data/products.json',
+          cache: true,
+          children: [
+            list({
+              id: 'products',
+              items: 'catalog.data.products',
+              children: [
+                // An attribute reads a name with filters, spelled in full.
+                link({
+                  href: '/products/{{ list_products.item.slug|url_encode }}',
+                  children: [text({ from: 'products.item.title' })]
+                })
+              ]
+            })
+          ]
+        })
+      ]
+    },
+    {
+      id: 'product',
+      name: 'Product',
+      slug: 'products/:slug',
+      body: [
+        apiContainer({
+          id: 'catalog-one',
+          query: '/data/products.json',
+          cache: true,
+          children: [
+            list({
+              id: 'this-product',
+              from: 'catalog-one.data.products',
+              as: '{{ source|filter(p => p.slug == navigation.routeParams.slug) }}',
+              visible: {
+                source: 'catalog-one.data.products',
+                template: "{{ source|find('slug', navigation.routeParams.slug) }}"
+              },
+              children: [heading({ subType: 'h1', from: 'this-product.item.title' })]
+            }),
+            text('No product by that name.', {
+              visible: {
+                source: 'catalog-one.data.products',
+                template: "{{ source is defined and not (source|find('slug', navigation.routeParams.slug)) }}"
+              }
+            })
+          ]
+        })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/embed-and-svg.ts

@@ -0,0 +1,48 @@
+/**
+ * Something drawn elsewhere — a map, a video player — in an `embed`, and a drawing of your own in an `svg`.
+ *
+ * An embed says what it shows in `title`, which is what a screen reader announces, and loads lazily. An `svg` takes
+ * the markup alone, checked to be an SVG and with anything that runs taken out; drawn with `currentColor`, it follows
+ * the colour of its class in both themes. Without a `label` it is decoration, hidden from readers; with one it is an
+ * image that says it.
+ */
+import { container, embed, heading, styles, svg } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+const frame = styles('map-frame', { aspectRatio: '16 / 9', width: '100%', borderRadius: '12px' });
+
+const badge = styles('badge-icon', { width: 24, height: 24, color: 'var(--primary)' });
+
+const CHECK =
+  '<svg viewBox="0 0 24 24" width="24" height="24" fill="none" stroke="currentColor" stroke-width="2">' +
+  '<path d="M5 12l5 5L20 7"/></svg>';
+
+export const recipe: SpaceSpec = {
+  name: 'Embeds',
+  permanentUrl: 'embeds',
+  variables: { color: { primary: { light: '#4f46e5', dark: '#818cf8', default: '#4f46e5' } } },
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        container({
+          subType: 'section',
+          children: [
+            heading('Find us', { subType: 'h2' }),
+            embed({
+              id: 'shop-map',
+              class: frame,
+              src: 'https://www.openstreetmap.org/export/embed.html?bbox=-3.71,40.41,-3.69,40.42',
+              title: 'Our shop on the map'
+            })
+          ]
+        }),
+        svg(CHECK, { class: badge }),
+        svg(CHECK, { class: badge, label: 'Verified' })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/every-few-seconds.ts

@@ -0,0 +1,119 @@
+/**
+ * Something every few seconds — here a carousel that turns by itself: `onInterval` moves `state.slide` on, a hover
+ * pauses it, arrows and dots move it by hand, and each slide enters with an animation.
+ *
+ * Every slide is rendered and all but one hidden by `visible`. A hidden element is `display: none`, so its CSS
+ * animation runs again each time it is shown: that is the entrance. The clock ticks only while the tab is in view.
+ */
+import {
+  button,
+  container,
+  cycleState,
+  heading,
+  list,
+  on,
+  onClick,
+  onInterval,
+  setState,
+  styles,
+  text,
+  activeWhen,
+  when
+} from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+const SLIDES = [
+  { title: 'New in store', body: 'This week’s arrivals.' },
+  { title: 'Free delivery', body: 'On orders over 50 €.' },
+  { title: 'Trade in', body: 'Your old card, against a new one.' }
+];
+
+// The slide after the last is the first: a cycle as long as the slides.
+const next = cycleState({ key: 'slide', length: SLIDES.length });
+const previous = cycleState({ key: 'slide', length: SLIDES.length, by: -1 });
+
+const slide = styles('slide', { padding: '48px 24px', animation: 'slide-in 400ms ease-out' });
+
+const dots = styles('dots', { display: 'flex', gap: '8px', margin: '0px', padding: '0px', 'list-style-type': 'none' });
+
+const dot = styles('dot', {
+  css: {
+    width: '10px',
+    height: '10px',
+    padding: '0px',
+    'border-radius': '999px',
+    border: '0px solid transparent',
+    'background-color': 'var(--muted)'
+  },
+  variants: { active: { 'background-color': 'var(--primary)' } }
+});
+
+export const recipe: SpaceSpec = {
+  name: 'Carousel',
+  permanentUrl: 'carousel',
+  variables: {
+    color: {
+      muted: { light: '#c4c4cc', dark: '#3a3a44', default: '#c4c4cc' },
+      primary: { light: '#4f46e5', dark: '#818cf8', default: '#4f46e5' }
+    }
+  },
+  customCss:
+    '@keyframes slide-in { from { opacity: 0; transform: translateX(24px); } to { opacity: 1; transform: none; } }',
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        container({
+          id: 'carousel',
+          subType: 'section',
+          label: 'Offers',
+          flows: [
+            // Each tick turns it, unless the pointer is on it.
+            [onInterval(5000), when({ field: 'state.carouselPaused', operator: '!=', value: 'true' }, next)],
+            [on('onMouseEnter'), setState({ key: 'carouselPaused', type: 'boolean', value: true })],
+            [on('onMouseLeave'), setState({ key: 'carouselPaused', type: 'boolean', value: false })]
+          ],
+          children: [
+            list({
+              id: 'slides',
+              items: SLIDES,
+              children: [
+                container({
+                  class: slide,
+                  visible: { source: 'slides.index', template: '{{ source == (state.slide ?? 0) }}' },
+                  children: [heading({ subType: 'h2', from: 'slides.item.title' }), text({ from: 'slides.item.body' })]
+                })
+              ]
+            }),
+            button({
+              content: 'Previous',
+              flows: [[onClick(), previous]]
+            }),
+            button({
+              content: 'Next',
+              flows: [[onClick(), next]]
+            }),
+            list({
+              id: 'dots',
+              class: dots,
+              items: SLIDES,
+              children: [
+                button({
+                  content: '',
+                  title: 'Show this offer',
+                  class: dot,
+                  bind: [activeWhen(dot, '{{ list_dots.index == (state.slide ?? 0) }}')],
+                  flows: [[onClick(), setState({ key: 'slide', type: 'number', value: '{{ list_dots.index }}' })]]
+                })
+              ]
+            }),
+            text({ from: 'state.slide', as: '{{ (source ?? 0) + 1 }} of 3' })
+          ]
+        })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/feature-flag.ts

@@ -0,0 +1,24 @@
+/**
+ * A feature behind a flag: declared once in the space, both versions gated — exactly one is ever rendered, and the
+ * flag is switched per environment without touching the space.
+ */
+import { container, text } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+export const recipe: SpaceSpec = {
+  name: 'Flags',
+  permanentUrl: 'flags',
+  flags: { newCheckout: { description: 'The one-step checkout', value: false, rules: [] } },
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        container({ id: 'checkout-new', flag: 'newCheckout', children: [text('One step')] }),
+        container({ id: 'checkout-old', flag: '!newCheckout', children: [text('Three steps')] })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/filter-a-list.ts

@@ -0,0 +1,63 @@
+/* eslint-disable quotes -- templates quote their own strings, and read best in the other quotes */
+/**
+ * Filter and sort a list: a select writes the chosen category to `state`, and the list is bound through a template
+ * that hands over its VALUE — only the matching rows are rendered, with a count and an empty state over the same rows.
+ */
+import { apiContainer, formControl, list, named, on, setState, text } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+// One predicate, read three times: the rows, their count, and whether there are none.
+const shown =
+  "source|filter(p => (state.category ?? 'all') == 'all' or p.category == state.category)|sort((a, b) => a.price - b.price)";
+
+export const recipe: SpaceSpec = {
+  name: 'Filtered',
+  permanentUrl: 'filtered',
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        // A control outside a form keeps its own value and fires `onChange` with `{ value, name }`: no form needed.
+        formControl({
+          name: 'category',
+          label: 'Category',
+          subType: 'select',
+          options: [
+            { label: 'Everything', value: 'all' },
+            { label: 'Processors', value: 'cpu' },
+            { label: 'Graphics cards', value: 'gpu' }
+          ],
+          defaultValue: 'all',
+          // A filter always has an answer: the select is not a question that must be filled in.
+          required: false,
+          flows: [
+            [named('picked', on('onChange')), setState({ key: 'category', type: 'text', value: '{{ picked.value }}' })]
+          ]
+        }),
+        apiContainer({
+          id: 'catalog',
+          query: '/data/products.json',
+          cache: true,
+          children: [
+            text({ from: 'catalog.data.products', as: `{{ ${shown}|length }} shown` }),
+            list({
+              id: 'shown',
+              from: 'catalog.data.products',
+              as: `{{ ${shown} }}`,
+              children: [text({ from: 'shown.item.title' })]
+            }),
+            text('Nothing in that category.', {
+              visible: {
+                source: 'catalog.data.products',
+                template: `{{ source is defined and ${shown}|length == 0 }}`
+              }
+            })
+          ]
+        })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/forms-and-modals.ts

@@ -0,0 +1,64 @@
+/**
+ * Do something on a click or a submit: a flow is `[trigger, steps…]`. A form manages its own submit and hands its
+ * values to the flow; a modal starts hidden and a step opens it.
+ */
+import {
+  button,
+  closeModal,
+  fontAwesome,
+  form,
+  formControl,
+  modalContainer,
+  named,
+  onClick,
+  onSubmit,
+  openModal,
+  setState,
+  text,
+  toggleState
+} from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+export const recipe: SpaceSpec = {
+  name: 'Flows',
+  permanentUrl: 'flows',
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        button({ content: 'Save', flows: [[onClick(), setState({ key: 'saved', type: 'boolean', value: true })]] }),
+        // A switch is named for how it leaves its default: shown until somebody hides it.
+        button({ content: 'Hide details', flows: [[onClick(), toggleState({ key: 'detailsHidden' })]] }),
+        form({
+          id: 'signup',
+          managedByInteractions: true,
+          flows: [
+            [named('sent', onSubmit()), setState({ key: 'email', type: 'text', value: '{{ sent.values.email }}' })]
+          ],
+          children: [
+            formControl({ name: 'email', label: 'Email', subType: 'email' }),
+            button({ content: 'Sign up', subType: 'submit' })
+          ]
+        }),
+        modalContainer({
+          id: 'details',
+          visible: false,
+          title: 'Details',
+          children: [
+            text('What the modal says.'),
+            button({
+              content: '',
+              title: 'Close',
+              children: [fontAwesome({ icon: 'fa-solid fa-xmark' })],
+              flows: [[onClick(), closeModal('details')]]
+            })
+          ]
+        }),
+        button({ content: 'Open', flows: [[onClick(), openModal('details')]] })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/from-tailwind.ts

@@ -0,0 +1,52 @@
+/**
+ * A design written in Tailwind classes, kept as classes the builder edits: `tw()` turns them into rules when the space
+ * is written. The space's colours stay tokens with both themes — `createTw({ colors: tokens(variables) })` — and
+ * Tailwind's own palette is there for the rest.
+ */
+import { container, createTw, heading, link, styles, text, tokens } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+const variables = {
+  color: {
+    surface: { light: '#ffffff', dark: '#0f172a', default: '#ffffff' },
+    ink: { light: '#0f172a', dark: '#e2e8f0', default: '#0f172a' },
+    accent: { light: '#0891b2', dark: '#22d3ee', default: '#0891b2' }
+  }
+} satisfies SpaceSpec['variables'];
+
+const tw = createTw({ colors: tokens(variables) });
+
+const grid = styles('feature-grid', tw('grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3'));
+// The card's title moves with the card's hover: an ancestor named by its class.
+const card = styles(
+  'feature-card',
+  tw('rounded-xl border border-ink/10 bg-surface p-6 transition-shadow hover:shadow-lg')
+);
+const title = styles('feature-title', tw('text-lg font-semibold text-ink group-hover/feature-card:text-accent'));
+const cta = styles(
+  'feature-cta',
+  tw('inline-flex items-center gap-2 rounded-full bg-accent px-5 py-2 text-sm font-medium text-white hover:scale-105')
+);
+
+export const recipe: SpaceSpec = {
+  name: 'Features',
+  permanentUrl: 'features',
+  variables,
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        container({
+          class: grid,
+          children: ['Fast', 'Typed', 'Yours'].map(name =>
+            container({ class: card, children: [heading(name, { subType: 'h3', class: title }), text('…')] })
+          )
+        }),
+        link({ href: '/start', class: cta, children: [text('Get started')] })
+      ]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/link-to-a-section.ts

@@ -0,0 +1,35 @@
+/**
+ * Link to a section: the section carries an `anchor` — its id in the page; an element's `id` is only its name in the
+ * space, `data-id` in the DOM — and a link's `hash` lands on it, from any page, even when the section renders late.
+ */
+import { container, heading, link, text } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+export const recipe: SpaceSpec = {
+  name: 'Sections',
+  permanentUrl: 'sections',
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        link({ href: 'home', hash: 'plans', children: [text('See the plans')] }),
+        container({
+          id: 'plans-section',
+          subType: 'section',
+          anchor: 'plans',
+          children: [heading('Plans', { subType: 'h2' }), text('Three of them.')]
+        })
+      ]
+    },
+    {
+      id: 'about',
+      name: 'About',
+      slug: 'about',
+      // → /#plans
+      body: [link({ href: 'home', hash: 'plans', children: [text('Plans')] })]
+    }
+  ]
+};

package/skills/plitzi-authoring/recipes/link-with-data.ts

@@ -0,0 +1,40 @@
+/**
+ * A link built from the row it is in — here "ask about this product" on WhatsApp, with the product's name in the
+ * message. An attribute resolves a name with filters, so the text is encoded with `url_encode`.
+ */
+import { apiContainer, fontAwesome, link, list, text } from '@plitzi/sdk-authoring';
+
+import type { SpaceSpec } from '@plitzi/sdk-authoring';
+
+export const recipe: SpaceSpec = {
+  name: 'Contact',
+  permanentUrl: 'contact',
+  pages: [
+    {
+      id: 'home',
+      name: 'Home',
+      slug: '',
+      body: [
+        apiContainer({
+          id: 'catalog',
+          query: '/data/products.json',
+          cache: true,
+          children: [
+            list({
+              id: 'products',
+              items: 'catalog.data.products',
+              children: [
+                link({
+                  target: 'blank',
+                  href: 'https://wa.me/34600000000?text={{ list_products.item.title|url_encode }}',
+                  children: [fontAwesome({ icon: 'fa-brands fa-whatsapp' }), text('Ask about it')]
+                }),
+                link({ href: 'mailto:shop@example.com', children: [text('Write to us')] })
+              ]
+            })
+          ]
+        })
+      ]
+    }
+  ]
+};