@pokela/components 2.4.2 → 2.5.1

package/README.md

@@ -1,6 +1,6 @@
 # @pokela/components
 
-React-komponentit: **Pokela Design System**, versio 2.4.2.
+React-komponentit: **Pokela Design System**, versio 2.5.1.
 
 > Generoitu hakemistosta `components/` — samoista tiedostoista joita sivusto
 > ajaa. Älä muokkaa käsin: muutokset tehdään lähteeseen ja paketti
@@ -21,6 +21,7 @@ tarvita.
 - `Icon`
 - `ListRow`
 - `Accordion`
+- `Timeline`
 - `Grid`
 - `Reveal`
 - `ThemeScript`
@@ -52,6 +53,7 @@ import Link from 'next/link';
 - `styles/icon.css`
 - `styles/list-row.css`
 - `styles/accordion.css`
+- `styles/timeline.css`
 
 Luokat ovat globaaleja, eivät CSS-moduuleja. Se on tarkoituksellista: sama
 luokka on myös Figmassa komponentin nimenä, ja hajautettu nimi katkaisisi

package/Timeline.d.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+/**
+ * Aikajana.
+ * ---------------------------------------------------------------
+ * Pystysuora jana: vasemmalla merkintä (aika, päivä, numero), keskellä
+ * kisko ja piste, oikealla otsikko, sivutieto ja kuvaus. Merkintä,
+ * kisko ja sisältö ovat listan ruudukon sarakkeita, jotta merkinnät
+ * asettuvat samaan linjaan; siksi `TimelineItem` piirretään aina
+ * `Timeline`-listan sisällä.
+ *
+ * `variant`:
+ *   default   ohut kisko, ontto piste
+ *   emphasis  paksu kisko ja täytetty piste: nostettu kohta
+ *   end       kisko päättyy pisteeseen: viimeinen kohta
+ *
+ * `weight` (0–1) venyttää kohdan kiskoa. Sillä pitkä vaihe näkyy jo
+ * pituudestaan, esimerkiksi keston osuutena koko ajasta.
+ */
+export default function Timeline({ children, className }: {
+    children: ReactNode;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export type TimelineVariant = 'default' | 'emphasis' | 'end';
+export declare function TimelineItem({ label, title, meta, description, group, variant, weight, }: {
+    label: string;
+    title: string;
+    meta?: string | null;
+    description?: string | null;
+    group?: string | null;
+    variant?: TimelineVariant;
+    weight?: number;
+}): import("react/jsx-runtime").JSX.Element;

package/Timeline.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Aikajana.
+ * ---------------------------------------------------------------
+ * Pystysuora jana: vasemmalla merkintä (aika, päivä, numero), keskellä
+ * kisko ja piste, oikealla otsikko, sivutieto ja kuvaus. Merkintä,
+ * kisko ja sisältö ovat listan ruudukon sarakkeita, jotta merkinnät
+ * asettuvat samaan linjaan; siksi `TimelineItem` piirretään aina
+ * `Timeline`-listan sisällä.
+ *
+ * `variant`:
+ *   default   ohut kisko, ontto piste
+ *   emphasis  paksu kisko ja täytetty piste: nostettu kohta
+ *   end       kisko päättyy pisteeseen: viimeinen kohta
+ *
+ * `weight` (0–1) venyttää kohdan kiskoa. Sillä pitkä vaihe näkyy jo
+ * pituudestaan, esimerkiksi keston osuutena koko ajasta.
+ */
+export default function Timeline({ children, className }) {
+    return _jsx("ol", { className: ['timeline', className].filter(Boolean).join(' '), children: children });
+}
+export function TimelineItem({ label, title, meta, description, group, variant = 'default', weight = 0, }) {
+    return (_jsxs("li", { className: ['timeline__item', variant === 'default' ? '' : `timeline__item--${variant}`].join(' '), style: { '--weight': weight.toFixed(3) }, children: [_jsx("span", { className: "meta faint timeline__label", children: label }), _jsx("span", { className: "timeline__rail", "aria-hidden": "true" }), _jsxs("span", { className: "timeline__body", children: [group ? _jsx("span", { className: "meta faint", children: group }) : null, _jsxs("span", { className: "timeline__head", children: [_jsx("span", { className: "body-l", children: title }), meta ? _jsx("span", { className: "meta faint", children: meta }) : null] }), description ? _jsx("span", { className: "body-s muted", children: description }) : null] })] }));
+}

package/guidelines/components.md

@@ -0,0 +1,49 @@
+# Components
+
+Use these instead of building an equivalent.
+
+<!-- generated:make-komponentit -->
+- `Icon`, `ICON_NAMES`
+- `ListRow`
+- `Accordion`, `useAccordionGroup`
+- `Timeline`, `TimelineItem`
+- `Grid`, `Col`
+- `Reveal`
+- `ThemeScript`, `THEME_STORAGE_KEY`
+- `ThemeToggle`
+<!-- /generated -->
+
+`ListRow` is the signature component. Use it for any list of items — a work
+list, an index, a menu. Its three visual variants are modifiers on one row,
+not separate components.
+
+`ListRow` renders a plain `<a>`. In a router-based app, pass the router's link
+component instead:
+
+```jsx
+<ListRow as={Link} title="Work title" href="/work/example" />
+```
+
+To show a row as selected, use `className="invert"` — not a new colour.
+
+`ListRow` already applies `bleed` itself. Do not pass it again in `className`.
+
+`Accordion` is the same row as a `<button>`. Use it when the row expands
+rather than navigates. Only one may be open at a time; `useAccordionGroup`
+handles that.
+
+`Timeline` is a vertical list of dated or timed items. Put `TimelineItem`s
+inside it; the labels line up because they share the list's grid. Use
+`variant="emphasis"` for the one item that matters most and `variant="end"`
+for the last. `weight` (0–1) stretches an item's rail, e.g. by its share of
+the total duration.
+
+```jsx
+<Timeline>
+  <TimelineItem label="0.00" title="Tokens" meta="under a second" />
+  <TimelineItem label="0.03" title="Images" meta="5 min 32 s" variant="emphasis" weight={0.9} />
+  <TimelineItem label="5.35" title="Site built" variant="end" />
+</Timeline>
+```
+
+`Reveal` fades its children in on scroll. Wrap sections, not single elements.

package/guidelines/setup.md

@@ -0,0 +1,28 @@
+# Setup
+
+Install **both** packages as direct dependencies, at the same, latest
+version. `@pokela/components` uses the tokens of the same release.
+
+Import the stylesheet once, in the app entry:
+
+```js
+import '@pokela/components/styles.css';
+```
+
+It pulls in the tokens. Do not import the tokens stylesheet separately.
+
+Load the two typefaces from Google Fonts, once, in the document head. The
+tokens fall back to them by name (`--font-display` → Bodoni Moda,
+`--font-ui` → Archivo); without them the page renders in Georgia and
+Helvetica.
+
+<!-- generated:make-fontit -->
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Archivo:wght@400;500;600&family=Bodoni+Moda:wght@400;500&display=swap" rel="stylesheet">
+```
+<!-- /generated -->
+
+Component props are typed. Read them from the package — they are not repeated
+in these guidelines, because a copy would go stale.

package/guidelines/styles.md

@@ -0,0 +1,34 @@
+# Styles
+
+**Do not use Tailwind utility classes for design system values.** This system
+is plain CSS: global classes that come with the components, and CSS variables
+for values. Writing `bg-blue-500` or `rounded-lg` bypasses the system and
+produces the wrong result.
+
+## Headings
+
+Typography classes set the look, not the meaning. A page heading is an `<h1>`,
+a section heading an `<h2>`, and so on — never a `<p>` carrying a display
+class. The class and the element are two separate decisions, and a screen
+reader only hears the element.
+
+```jsx
+<h1 className="display-xl">Selected work</h1>
+```
+
+## Typography
+
+Two families. `--font-display` (Bodoni Moda, a serif) is for display sizes
+only — headings and the wordmark. `--font-ui` (Archivo) is for everything
+else. Never set body text in the display face.
+
+<!-- generated:make-painot -->**No font weight other than 400, 500 or 600.**<!-- /generated --> Only those are loaded, and
+`font-synthesis-weight` is `none`, so any other weight silently renders wrong.
+
+## Layout
+
+<!-- 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
+a 16×16 grid with the same hairline as every border.

package/guidelines/tokens.md

@@ -0,0 +1,18 @@
+# Tokens
+
+Use CSS variables for every value: `var(--ink)`, `var(--space-24)`,
+`var(--hairline)`. Never write a raw colour, length or font weight.
+
+**No accent colour.** This system has none. Emphasis is a black and white
+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.
+
+**No shadows.** There are no shadow tokens. Separation is a 1px line
+(`--hairline`), never elevation.
+
+**No rounded corners.** `--radius` is `0`. Everything is square.
+
+<!-- generated:make-valit -->**No spacing outside the scale.** 16 steps, each named by its value:<!-- /generated -->
+`--space-24` is 24px. If a value is missing, use the nearest step rather than
+inventing one.

package/index.d.ts

@@ -4,6 +4,8 @@ export { default as ListRow } from './ListRow.js';
 export type { ListRowProps } from './ListRow.js';
 export { Accordion, useAccordionGroup } from './Accordion.js';
 export type { AccordionProps } from './Accordion.js';
+export { default as Timeline, TimelineItem } from './Timeline.js';
+export type { TimelineVariant } from './Timeline.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

@@ -2,6 +2,7 @@
 export { default as Icon, ICON_NAMES } from './Icon.js';
 export { default as ListRow } from './ListRow.js';
 export { Accordion, useAccordionGroup } from './Accordion.js';
+export { default as Timeline, TimelineItem } from './Timeline.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.4.2",
+  "version": "2.5.1",
   "description": "React-komponentit: Pokela Design System. Generoitu tiedostoista components/, ei käsin ylläpidetty.",
   "license": "MIT",
   "author": "Veli-Matti Pokela",
@@ -21,11 +21,12 @@
     "*.d.ts",
     "styles.css",
     "styles/",
+    "guidelines/",
     "README.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@pokela/tokens": "^2.4.2"
+    "@pokela/tokens": "^2.5.1"
   },
   "peerDependencies": {
     "react": ">=18"

package/styles/timeline.css

@@ -0,0 +1,39 @@
+/* Aikajana (components/Timeline.tsx). Merkintä, kisko ja sisältö ovat
+   listan ruudukon sarakkeita, jotta merkinnät asettuvat samaan
+   linjaan; kohta itse on display: contents. Kisko venyy kohdan
+   painon mukaan (--weight): pitkä vaihe näkyy jo pituudestaan. */
+.timeline {
+  display: grid;
+  grid-template-columns: max-content var(--space-16) minmax(0, 1fr);
+  column-gap: var(--space-16);
+  margin: 0; padding: 0; list-style: none;
+}
+.timeline__item { display: contents; }
+.timeline__label { text-align: right; font-variant-numeric: tabular-nums; }
+.timeline__rail { position: relative; }
+.timeline__rail::before {
+  content: ''; position: absolute; top: 0; bottom: 0;
+  left: calc(50% - var(--hairline) / 2);
+  border-left: var(--hairline) solid var(--line);
+}
+.timeline__rail::after {
+  content: ''; position: absolute; top: var(--space-4);
+  left: calc(50% - var(--space-4));
+  width: var(--space-8); height: var(--space-8);
+  border-radius: 50%;
+  border: var(--hairline) solid var(--ink);
+  background: var(--paper);
+}
+.timeline__body {
+  display: flex; flex-direction: column; gap: var(--space-4);
+  padding-bottom: calc(var(--space-24) + var(--space-56) * 4 * var(--weight, 0));
+}
+.timeline__head { display: flex; justify-content: space-between; align-items: baseline; gap: var(--space-16); }
+.timeline__item--emphasis .timeline__rail::before {
+  left: calc(50% - var(--hairline-strong) / 2);
+  border-left: var(--hairline-strong) solid var(--ink);
+}
+.timeline__item--emphasis .timeline__rail::after { background: var(--ink); }
+.timeline__item--end .timeline__rail::before { bottom: auto; height: var(--space-4); }
+.timeline__item--end .timeline__rail::after { background: var(--ink); }
+.timeline__item--end .timeline__body { padding-bottom: 0; }

package/styles.css

@@ -4,3 +4,4 @@
 @import './styles/icon.css';
 @import './styles/list-row.css';
 @import './styles/accordion.css';
+@import './styles/timeline.css';