@pokela/components 2.7.0 → 2.9.0

package/Icon.d.ts

@@ -18,11 +18,14 @@
  * Koot ovat tokeneita: --icon-s (12) tekstin seassa metan kanssa,
  * --icon-m (16) napin sisällä, --icon-l (24) omana painikkeenaan.
  *
+ * `alert` kulkee aina virhetekstin rinnalla, ei yksin: merkitys on
+ * tekstissä, ikoni ja --danger vain nopeuttavat sen löytämistä.
+ *
  * Nuoli on kahta lajia eikä yhtä: `arrow-right` vie sivustolla eteen-
  * päin, `arrow-up-right` ulos. Ero on lukijalle sama kuin
  * target="_blank" ruudunlukijalle.
  */
-export type IconName = 'arrow-right' | 'arrow-up-right' | 'plus' | 'minus' | 'close' | 'menu';
+export type IconName = 'arrow-right' | 'arrow-up-right' | 'plus' | 'minus' | 'close' | 'menu' | 'alert';
 export type IconSize = 's' | 'm' | 'l';
 export type IconProps = {
     name: IconName;

package/Icon.js

@@ -8,6 +8,10 @@ const PATHS = {
     minus: ['M2.5 8.5 H14.5'],
     close: ['M3.5 3.5 L12.5 12.5', 'M12.5 3.5 L3.5 12.5'],
     menu: ['M1 5.5 H15', 'M1 10.5 H15'],
+    /* Virhe. Neliö eikä kolmio tai ympyrä: kaaria ei ole, ja kolmion
+       vinot sivut eivät osu puolikkaan pikselin ruudukolle. Piste on
+       lyhyt viiva, koska täyttöä ei ole. */
+    alert: ['M2.5 2.5 H14.5 V14.5 H2.5 Z', 'M8.5 5 V10', 'M8.5 11.5 V12.5'],
 };
 export default function Icon({ name, size = 'm', label, className }) {
     return (_jsx("svg", { className: ['icon', `icon--${size}`, className].filter(Boolean).join(' '), viewBox: "0 0 16 16", role: label ? 'img' : undefined, "aria-label": label, "aria-hidden": label ? undefined : true, focusable: "false", children: PATHS[name].map((d) => (_jsx("path", { d: d }, d))) }));

package/PageHeader.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+/**
+ * Sivun otsikko (pattern).
+ * ---------------------------------------------------------------
+ * Patterni ei tuo omaa ulkoasua: se asettelee olemassa olevat
+ * typografialuokat aina samalla tavalla. Otsikko (`display-xl`) ja
+ * sivutieto (`meta`) ovat samalla rivillä leveämmällä ruudulla,
+ * ingressi (`body-l`) otsikon alla samassa sarakkeessa.
+ *
+ * Ennen tätä sama rakenne kirjoitettiin jokaiselle sivulle käsin, ja
+ * Figma Make arvasi sen: ingressi päätyi sarakkeisiin 9–12, irti
+ * otsikosta (päätös 21).
+ */
+export default function PageHeader({ title, meta, lede, }: {
+    title: ReactNode;
+    meta?: ReactNode;
+    lede?: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/PageHeader.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Sivun otsikko (pattern).
+ * ---------------------------------------------------------------
+ * Patterni ei tuo omaa ulkoasua: se asettelee olemassa olevat
+ * typografialuokat aina samalla tavalla. Otsikko (`display-xl`) ja
+ * sivutieto (`meta`) ovat samalla rivillä leveämmällä ruudulla,
+ * ingressi (`body-l`) otsikon alla samassa sarakkeessa.
+ *
+ * Ennen tätä sama rakenne kirjoitettiin jokaiselle sivulle käsin, ja
+ * Figma Make arvasi sen: ingressi päätyi sarakkeisiin 9–12, irti
+ * otsikosta (päätös 21).
+ */
+export default function PageHeader({ title, meta, lede, }) {
+    return (_jsxs("header", { className: "page page-header", children: [_jsxs("div", { className: "page-head", children: [_jsx("h1", { className: "display-xl", children: title }), meta ? _jsx("p", { className: "meta", children: meta }) : null] }), lede ? _jsx("p", { className: "body-l measure page-header__lede", children: lede }) : null] }));
+}

package/README.md

@@ -1,6 +1,6 @@
 # @pokela/components
 
-React-komponentit: **Pokela Design System**, versio 2.7.0.
+React-komponentit: **Pokela Design System**, versio 2.9.0.
 
 > Generoitu hakemistosta `components/` — samoista tiedostoista joita sivusto
 > ajaa. Älä muokkaa käsin: muutokset tehdään lähteeseen ja paketti
@@ -23,6 +23,9 @@ tyylit saa myös suoraan: `@pokela/components/styles.css`.
 - `Accordion`
 - `Timeline`
 - `ExplodedView`
+- `PageHeader`
+- `Section`
+- `TextField`
 - `Grid`
 - `Reveal`
 - `ThemeScript`
@@ -57,6 +60,8 @@ import Link from 'next/link';
 - `styles/accordion.css`
 - `styles/timeline.css`
 - `styles/exploded-view.css`
+- `styles/patterns.css`
+- `styles/text-field.css`
 
 Luokat ovat globaaleja, eivät CSS-moduuleja. Se on tarkoituksellista: sama
 luokka on myös Figmassa komponentin nimenä, ja hajautettu nimi katkaisisi

package/Section.d.ts

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+/**
+ * Osio (pattern).
+ * ---------------------------------------------------------------
+ * Sivun osio otsikkoineen. Kaksi asettelua, molemmat sivustolta:
+ *
+ *   stacked  otsikko ja sivutieto rivinä, sisältö alla
+ *            (työlista, Tietoa, System)
+ *   aside    otsikko vasemmassa sarakkeessa, sisältö oikealla;
+ *            pienellä ruudulla päällekkäin (casesivujen lohkot)
+ *
+ * Otsikko on aina `h2.meta`: se nimeää osion, sisällön oma otsikko
+ * (esim. `display-m`) kuuluu `children`-osaan.
+ */
+export type SectionLayout = 'stacked' | 'aside';
+export default function Section({ title, meta, id, layout, className, children, }: {
+    title: ReactNode;
+    meta?: ReactNode;
+    /** Otsikon id; osio nimetään sillä (`aria-labelledby`). */
+    id?: string;
+    layout?: SectionLayout;
+    className?: string;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/Section.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export default function Section({ title, meta, id, layout = 'stacked', className, children, }) {
+    const otsikko = (_jsx("h2", { id: id, className: "meta", children: title }));
+    if (layout === 'aside') {
+        return (_jsxs("section", { className: ['page section--aside', className].filter(Boolean).join(' '), "aria-labelledby": id, children: [otsikko, children] }));
+    }
+    return (_jsxs("section", { className: ['page section', className].filter(Boolean).join(' '), "aria-labelledby": id, children: [_jsxs("div", { className: "section-head", children: [otsikko, meta ? _jsx("span", { className: "meta", children: meta }) : null] }), children] }));
+}

package/TextField.d.ts

@@ -0,0 +1,35 @@
+import { type InputHTMLAttributes } from 'react';
+/**
+ * Tekstikenttä: label, kenttä, ohjeteksti ja virhe yhtenä.
+ *
+ * Sivusto ei käytä tätä. Se on kirjastossa sovellusnäkymiä varten
+ * (päätös 22), jotta Make voi rakentaa
+ * lomakkeen systeemin omista osista eikä keksi omaansa.
+ *
+ * Kieli on .btn-perheen: hiusviiva ilman pyöristystä, hover paksuntaa
+ * alaviivan kuten tekstinapissa, focus on sivuston yhteinen rengas.
+ * Virhe on systeemin ainoa tilaväri --danger, aina ikonin ja tekstin
+ * kanssa, ettei merkitys jää värin varaan.
+ *
+ * Tilat ovat propseja, eivät luokkia: `error` ja `disabled`. Hover ja
+ * focus ovat CSS:n tiloja. `multiline` vaihtaa kentän tekstialueeksi;
+ * muuten sama komponentti, koska label, ohje ja virhe ovat samat.
+ */
+type Yhteiset = {
+    label: string;
+    /** Ohjeteksti kentän alla. */
+    hint?: string;
+    /** Virheviesti. Kun annettu, kenttä on virhetilassa (aria-invalid). */
+    error?: string;
+    /** Valinnaisen kentän merkintä labelin perässä, esim. "(valinnainen)". */
+    optional?: string;
+    className?: string;
+};
+export type TextFieldProps = Yhteiset & Omit<InputHTMLAttributes<HTMLInputElement>, 'className'> & {
+    /** Tekstialue (<textarea>) yhden rivin kentän sijaan. */
+    multiline?: boolean;
+    /** Tekstialueen rivit. */
+    rows?: number;
+};
+export default function TextField(props: TextFieldProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/TextField.js

@@ -0,0 +1,20 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useId } from 'react';
+import Icon from './Icon';
+export default function TextField(props) {
+    const { label, hint, error, optional, className, multiline, rows, id: annettuId, ...kentta } = props;
+    const omaId = useId();
+    const id = annettuId ?? omaId;
+    const ohjeId = hint ? `${id}-ohje` : undefined;
+    const virheId = error ? `${id}-virhe` : undefined;
+    const kuvaus = [ohjeId, virheId].filter(Boolean).join(' ') || undefined;
+    const yhteiset = {
+        id,
+        className: 'field__control',
+        'aria-invalid': error ? true : undefined,
+        'aria-describedby': kuvaus,
+    };
+    return (_jsxs("div", { className: ['field', error && 'field--invalid', kentta.disabled && 'field--disabled', className]
+            .filter(Boolean)
+            .join(' '), children: [_jsxs("label", { className: "field__label", htmlFor: id, children: [label, optional ? _jsxs("span", { className: "field__optional", children: [" ", optional] }) : null] }), multiline ? (_jsx("textarea", { ...kentta, rows: rows, ...yhteiset })) : (_jsx("input", { ...kentta, ...yhteiset })), hint ? (_jsx("p", { id: ohjeId, className: "field__hint", children: hint })) : null, error ? (_jsxs("p", { id: virheId, className: "field__error", children: [_jsx(Icon, { name: "alert" }), error] })) : null] }));
+}

package/guidelines/components.md

@@ -8,6 +8,9 @@ Use these instead of building an equivalent.
 - `Accordion`, `useAccordionGroup`
 - `Timeline`, `TimelineItem`
 - `ExplodedView`
+- `PageHeader`
+- `Section`
+- `TextField`
 - `Grid`, `Col`
 - `Reveal`
 - `ThemeScript`, `THEME_STORAGE_KEY`
@@ -69,4 +72,35 @@ reader, described by `label`.
 />
 ```
 
+`TextField` is the form field: label, input, hint and error in one. Use it
+for every text input and text area (`multiline`) instead of a bare `<input>`.
+Pass `error` with a message to show the error state; never colour a field
+yourself. Mark an optional field with `optional="(optional)"`, not an asterisk
+on the required ones. Put form buttons after the fields with the `.btn`
+classes.
+
+```jsx
+<TextField label="Email" type="email" error="The address is missing a domain." />
+<TextField label="Message" optional="(optional)" multiline hint="Up to 500 characters." />
+## Patterns
+
+`PageHeader` and `Section` are patterns: they add no look of their own, only
+the layout every page uses. Build pages from them instead of arranging
+headings and grids yourself.
+
+`PageHeader` is the page's title with an optional `meta` and `lede`. The lede
+always sits under the title in the same column, never beside it.
+
+`Section` names a part of the page with a small `title` (and optional
+`meta`). `layout="stacked"` puts the title row above the content;
+`layout="aside"` puts the title in a narrow left column and the content
+beside it. Use one layout per page.
+
+```jsx
+<PageHeader title="From idea to launch" meta="9 weeks" lede="Each phase ends in a shared decision." />
+<Section title="Road to launch" layout="aside">
+  <Timeline>…</Timeline>
+</Section>
+```
+
 `Reveal` fades its children in on scroll. Wrap sections, not single elements.

package/guidelines/setup.md

@@ -1,5 +1,27 @@
 # Setup
 
+## Before you build
+
+First decide which of three jobs this is. If the request does not make it
+clear, ask this one question and wait: **"Are you building a view, a new
+component, or a change to an existing component?"**
+
+1. **A view or prototype**, new or existing. Ask what the page is, what is
+   on it and what can be clicked. Build it only from this package: pages
+   start with `PageHeader`, content goes in `Section`s. If the view needs a
+   part the package does not have, do not invent it inside the view: build
+   it separately as in 2 and label it "Proposed component".
+2. **A new component.** Ask its name, what it does, its states, and which
+   existing component is closest. Build it alone on an empty page, every
+   state visible side by side, using only tokens. Name its props like the
+   package's components (`variant`, `size`, `title`, `meta`), so it can
+   become a pull request and a story as is.
+3. **A change to an existing component.** Package components cannot be
+   edited here. Show the change as a new state next to the current one and
+   label it "Proposed change".
+
+## Install
+
 Install **both** packages as direct dependencies, at the same, latest
 version. `@pokela/components` uses the tokens of the same release.
 

package/guidelines/styles.md

@@ -30,5 +30,5 @@ else. Never set body text in the display face.
 <!-- generated:make-sarakkeet -->`Grid` is 12 columns: 4 on mobile, 8 from 600px, 12 from 900px.<!-- /generated --> Place
 things in columns, never in pixels. `Col` takes the span per breakpoint.
 
-**No icon libraries and no emoji.** Use `Icon`. <!-- generated:make-ikonit -->It draws its own 6 marks<!-- /generated --> on
+**No icon libraries and no emoji.** Use `Icon`. <!-- generated:make-ikonit -->It draws its own 7 marks<!-- /generated --> on
 a 16×16 grid with the same hairline as every border.

package/guidelines/tokens.md

@@ -8,6 +8,10 @@ inversion — `--invert-surface` with `--invert-ink` — or the quiet
 `--badge-surface`. Do not introduce a brand blue, a primary green, or any
 coloured button. Colour on the page comes only from photographs.
 
+The one exception is `--danger`, a state colour for errors only. Do not use it
+for emphasis, buttons or decoration. `TextField` already applies it, always
+with the `alert` icon and a message, so the meaning never depends on colour.
+
 **No shadows.** There are no shadow tokens. Separation is a 1px line
 (`--hairline`), never elevation.
 

package/index.d.ts

@@ -9,6 +9,11 @@ export { default as Timeline, TimelineItem } from './Timeline.js';
 export type { TimelineVariant } from './Timeline.js';
 export { default as ExplodedView } from './ExplodedView.js';
 export type { ExplodedTila, ExplodedLayer } from './ExplodedView.js';
+export { default as PageHeader } from './PageHeader.js';
+export { default as Section } from './Section.js';
+export type { SectionLayout } from './Section.js';
+export { default as TextField } from './TextField.js';
+export type { TextFieldProps } from './TextField.js';
 export { Grid, Col } from './Grid.js';
 export { default as Reveal } from './Reveal.js';
 export { default as ThemeScript, THEME_STORAGE_KEY } from './ThemeScript.js';

package/index.js

@@ -5,6 +5,9 @@ export { default as ListRow } from './ListRow.js';
 export { Accordion, useAccordionGroup } from './Accordion.js';
 export { default as Timeline, TimelineItem } from './Timeline.js';
 export { default as ExplodedView } from './ExplodedView.js';
+export { default as PageHeader } from './PageHeader.js';
+export { default as Section } from './Section.js';
+export { default as TextField } from './TextField.js';
 export { Grid, Col } from './Grid.js';
 export { default as Reveal } from './Reveal.js';
 export { default as ThemeScript, THEME_STORAGE_KEY } from './ThemeScript.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pokela/components",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "React-komponentit: Pokela Design System. Generoitu tiedostoista components/, ei käsin ylläpidetty.",
   "license": "MIT",
   "author": "Veli-Matti Pokela",
@@ -27,7 +27,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@pokela/tokens": "^2.7.0"
+    "@pokela/tokens": "^2.9.0"
   },
   "peerDependencies": {
     "react": ">=18"

package/styles/patterns.css

@@ -0,0 +1,38 @@
+/* Patternit: sivun otsikko ja osio (PageHeader, Section).
+   Eivät tuo omaa ulkoasua, vain asettelun olemassa oleville
+   typografialuokille. Siirretty work.css:stä ja case.css:stä, jotta
+   ne lähtevät paketin mukana (päätös 21). */
+
+.page-head {
+  padding-top: var(--space-40);
+  padding-bottom: var(--space-32);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-12);
+}
+@media (min-width: 600px) {
+  .page-head { flex-direction: row; align-items: baseline; justify-content: space-between; gap: var(--space-24); }
+}
+@media (min-width: 900px) { .page-head { padding-top: var(--space-56); padding-bottom: var(--space-40); } }
+
+/* Ingressi otsikon alla, samassa sarakkeessa. */
+.page-header__lede { margin: 0; padding-bottom: var(--space-40); }
+
+.section-head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: var(--space-16);
+  padding-bottom: var(--space-16);
+}
+
+.section--aside {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  gap: var(--space-20);
+  padding-block: var(--section-gap);
+  border-top: var(--hairline) solid var(--line);
+}
+@media (min-width: 900px) {
+  .section--aside { grid-template-columns: 200px minmax(0, 1fr); gap: var(--space-40); }
+}

package/styles/text-field.css

@@ -0,0 +1,91 @@
+/* Tekstikenttä (TextField). Sovellusnäkymien komponentti, ei sivuston.
+   ==================================================================
+   Sama kieli kuin .btn: hiusviiva, ei pyöristystä, ei varjoa. Kenttä
+   on 48 px, nappia (44) korkeampi: 16 px:n teksti rivivälillä 1.65
+   tarvitsee tilaa, ja kirjoitettava pinta saa olla painettavaa
+   suurempi. */
+
+.field { display: grid; gap: var(--space-8); align-content: start; }
+
+.field__label {
+  font-size: var(--text-body-s);
+  line-height: var(--lh-body-s);
+  font-weight: var(--weight-500);
+  color: var(--ink);
+}
+.field__optional { font-weight: var(--weight-400); color: var(--ink-faint); }
+
+.field__control {
+  appearance: none;
+  width: 100%;
+  margin: 0;
+  /* 16 px eikä body-s: iOS zoomaa alle 16 px:n kentät. */
+  font: inherit;
+  font-size: var(--text-body);
+  line-height: var(--lh-body);
+  color: var(--ink);
+  background: var(--paper);
+  height: var(--space-48);
+  padding: 0 var(--space-16);
+  border: var(--hairline) solid var(--line-strong);
+  border-radius: var(--radius);
+  transition: border-color var(--dur-fast) var(--ease-standard);
+}
+.field__control::placeholder { color: var(--ink-faint); opacity: 1; }
+
+textarea.field__control {
+  height: auto;
+  min-height: var(--space-128);
+  padding: var(--space-12) var(--space-16);
+  resize: vertical;
+}
+
+/* Hover = alaviiva paksunee, sama liike kuin .btn--text:llä. Kenttä
+   on border-box ja kiinteän korkuinen, joten mitään ei nytkähdä. */
+.field__control:hover:not(:disabled) { border-bottom-width: var(--hairline-strong); }
+
+.field__hint {
+  margin: 0;
+  font-size: var(--text-body-s);
+  line-height: var(--lh-body-s);
+  color: var(--ink-muted);
+}
+
+/* ---- virhe ------------------------------------------------------- */
+
+/* Koko reuna paksunee, ei vain alaviiva: virhe ei saa näyttää
+   hoverilta. Padding kevenee saman verran, joten teksti pysyy
+   paikallaan. */
+.field--invalid .field__control {
+  border-color: var(--danger);
+  border-width: var(--hairline-strong);
+  padding-inline: calc(var(--space-16) - (var(--hairline-strong) - var(--hairline)));
+}
+.field--invalid textarea.field__control {
+  padding-block: calc(var(--space-12) - (var(--hairline-strong) - var(--hairline)));
+}
+
+.field__error {
+  margin: 0;
+  display: flex;
+  gap: var(--space-8);
+  align-items: flex-start;
+  font-size: var(--text-body-s);
+  line-height: var(--lh-body-s);
+  font-weight: var(--weight-500);
+  color: var(--danger);
+}
+/* Ikoni ensimmäisen rivin keskelle: (rivinkorkeus − ikoni) / 2. */
+.field__error .icon { margin-top: calc((var(--lh-body-s) * var(--text-body-s) - var(--icon-m)) / 2); }
+
+/* ---- disabled ---------------------------------------------------- */
+
+/* Sama kuin .btn[disabled]: viiva haalenee, teksti faint. Pinta on
+   paper-alt, jotta tyhjäkin kenttä erottuu käytössä olevasta. */
+.field--disabled .field__label { color: var(--ink-faint); }
+.field__control:disabled {
+  background: var(--paper-alt);
+  border-color: var(--line);
+  color: var(--ink-faint);
+  cursor: not-allowed;
+}

package/styles.css

@@ -7,3 +7,5 @@
 @import './styles/accordion.css';
 @import './styles/timeline.css';
 @import './styles/exploded-view.css';
+@import './styles/patterns.css';
+@import './styles/text-field.css';