@mxfb/tools 1.0.5 → 1.0.8

package/components/Date/index.d.ts

@@ -0,0 +1,45 @@
+import type { FunctionComponent } from 'react';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the {@link DateComponent} component.
+ *
+ * @property date - The moment to render. An invalid `Date` renders nothing at all.
+ * @property format - The template, in `formatDate`'s own grammar:
+ * `'{{YYYY}}-{{MM}}-{{DD}}'`. Everything outside `{{…}}` is a literal.
+ * @property locale - Handed to `formatDate`, which localises month and weekday names.
+ * @property dateTime - The machine-readable value the `<time>` element carries. Left
+ * out, the date's ISO string is used; `null` leaves the attribute off, for a precision
+ * HTML has no form for — a month without its year, a day without its month.
+ */
+export type Props = WithClassName<{
+    date: Date;
+    format: string;
+    locale?: string;
+    dateTime?: string | null;
+}>;
+/**
+ * `formatDate`, rendered one element per piece of the template rather than as a string.
+ *
+ * ### CSS elements
+ * - `part` — one per token, carrying as a modifier the unit it renders: `day`,
+ *   `weekday`, `month`, `year`, `hours`, `minutes`, `seconds`, `milliseconds`,
+ *   `meridiem`, `ordinal`. Carries `data-token` with the token itself.
+ * - `literal` — one per run of text between two tokens, separators included.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A `<time>` element holding one element per piece of the template.
+ *
+ * @remarks
+ * Not one token's meaning is implemented here: each is handed back to `formatDate` on
+ * its own, so what `MMMM` says in French stays that function's business, and the text
+ * rendered is character-for-character what it returns for the same template.
+ *
+ * An unknown token comes out a literal, braces included, which is what `formatDate` does
+ * with one — a typo shows rather than silently rendering nothing.
+ *
+ * The root carries no modifier, the component holding no state of its own; and a token
+ * being a name rather than a value a stylesheet computes with, it goes to a `data-`
+ * attribute and not to a custom property.
+ */
+export declare const DateComponent: FunctionComponent<Props>;

package/components/Date/index.js

@@ -0,0 +1,65 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { clss } from '@design-edito/tools/agnostic/css/clss/index.js';
+import { formatDate } from '@design-edito/tools/agnostic/time/dates/format-date/index.js';
+import { date as publicClassName } from '../public-classnames.js';
+import { mergeClassNames } from '../utils/index.js';
+import { dateTokenUnits } from './types.js';
+import cssModule from './styles.module.css';
+const templateToken = /\{\{([^\{\}]+)\}\}/gv;
+function isDateToken(raw) {
+    return Object.hasOwn(dateTokenUnits, raw);
+}
+function toPieces(format) {
+    const pieces = [];
+    let cursor = 0;
+    for (const match of format.matchAll(templateToken)) {
+        const raw = match[1] ?? '';
+        if (match.index > cursor)
+            pieces.push({ kind: 'literal', text: format.slice(cursor, match.index) });
+        if (isDateToken(raw)) {
+            pieces.push({ kind: 'token', token: raw });
+        }
+        else {
+            pieces.push({ kind: 'literal', text: match[0] });
+        }
+        cursor = match.index + match[0].length;
+    }
+    if (cursor < format.length)
+        pieces.push({ kind: 'literal', text: format.slice(cursor) });
+    return pieces;
+}
+/**
+ * `formatDate`, rendered one element per piece of the template rather than as a string.
+ *
+ * ### CSS elements
+ * - `part` — one per token, carrying as a modifier the unit it renders: `day`,
+ *   `weekday`, `month`, `year`, `hours`, `minutes`, `seconds`, `milliseconds`,
+ *   `meridiem`, `ordinal`. Carries `data-token` with the token itself.
+ * - `literal` — one per run of text between two tokens, separators included.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A `<time>` element holding one element per piece of the template.
+ *
+ * @remarks
+ * Not one token's meaning is implemented here: each is handed back to `formatDate` on
+ * its own, so what `MMMM` says in French stays that function's business, and the text
+ * rendered is character-for-character what it returns for the same template.
+ *
+ * An unknown token comes out a literal, braces included, which is what `formatDate` does
+ * with one — a typo shows rather than silently rendering nothing.
+ *
+ * The root carries no modifier, the component holding no state of its own; and a token
+ * being a name rather than a value a stylesheet computes with, it goes to a `data-`
+ * attribute and not to a custom property.
+ */
+export const DateComponent = ({ className, date, format, locale, dateTime }) => {
+    if (Number.isNaN(date.getTime()))
+        return null;
+    const machineValue = dateTime === undefined ? date.toISOString() : dateTime;
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(), className);
+    return _jsx("time", { className: rootClss, dateTime: machineValue ?? undefined, children: toPieces(format).map((piece, index) => piece.kind === 'literal'
+            ? _jsx("span", { className: c('literal'), children: piece.text }, index)
+            : _jsx("span", { className: c('part', dateTokenUnits[piece.token]), "data-token": piece.token, children: formatDate(date, `{{${piece.token}}}`, locale) }, index)) });
+};

package/components/Date/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What each token of a template is a token *of*.
+ *
+ * A part's modifier names the unit rather than the token, because what a stylesheet has
+ * an opinion about is the year, whether the template asked for `YY` or `YYYY`. The token
+ * itself stays on the element, as `data-token`, for the once in a while when the padding
+ * is the thing being styled.
+ *
+ * A table rather than a bare union: a consumer writing that stylesheet needs the values
+ * at runtime, and a type has nothing to hand them.
+ */
+export declare const dateTokenUnits: {
+    readonly D: "day";
+    readonly DD: "day";
+    readonly d: "day";
+    readonly dd: "day";
+    readonly ddd: "weekday";
+    readonly dddd: "weekday";
+    readonly M: "month";
+    readonly MM: "month";
+    readonly MMM: "month";
+    readonly MMMM: "month";
+    readonly YY: "year";
+    readonly YYYY: "year";
+    readonly H: "hours";
+    readonly HH: "hours";
+    readonly h: "hours";
+    readonly hh: "hours";
+    readonly m: "minutes";
+    readonly mm: "minutes";
+    readonly s: "seconds";
+    readonly ss: "seconds";
+    readonly ms: "milliseconds";
+    readonly A: "meridiem";
+    readonly a: "meridiem";
+    readonly th: "ordinal";
+};
+/** The unit a part names, which is the modifier a stylesheet targets. */
+export type DateUnit = typeof dateTokenUnits[keyof typeof dateTokenUnits];

package/components/Date/types.js

@@ -0,0 +1,37 @@
+/**
+ * What each token of a template is a token *of*.
+ *
+ * A part's modifier names the unit rather than the token, because what a stylesheet has
+ * an opinion about is the year, whether the template asked for `YY` or `YYYY`. The token
+ * itself stays on the element, as `data-token`, for the once in a while when the padding
+ * is the thing being styled.
+ *
+ * A table rather than a bare union: a consumer writing that stylesheet needs the values
+ * at runtime, and a type has nothing to hand them.
+ */
+export const dateTokenUnits = {
+    D: 'day',
+    DD: 'day',
+    d: 'day',
+    dd: 'day',
+    ddd: 'weekday',
+    dddd: 'weekday',
+    M: 'month',
+    MM: 'month',
+    MMM: 'month',
+    MMMM: 'month',
+    YY: 'year',
+    YYYY: 'year',
+    H: 'hours',
+    HH: 'hours',
+    h: 'hours',
+    hh: 'hours',
+    m: 'minutes',
+    mm: 'minutes',
+    s: 'seconds',
+    ss: 'seconds',
+    ms: 'milliseconds',
+    A: 'meridiem',
+    a: 'meridiem',
+    th: 'ordinal'
+};

package/components/Embed/SpotifyEmbed/index.d.ts

@@ -0,0 +1,13 @@
+import type { FunctionComponent } from 'react';
+import type { PlatformProps } from '../types.js';
+/**
+ * A Spotify track, album, playlist, episode or show, embedded from its canonical URL.
+ *
+ * ### Root element modifiers
+ * - `--link` — nothing embeddable could be read, so a link is rendered instead.
+ *
+ * @param props - Component properties.
+ * @see {@link PlatformProps}
+ * @returns An `<iframe>` on `open.spotify.com/embed/…`, or an `<a>` on the URL as given.
+ */
+export declare const SpotifyEmbed: FunctionComponent<PlatformProps>;

package/components/Embed/SpotifyEmbed/index.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { clss } from '@design-edito/tools/agnostic/css/clss/index.js';
+import { spotifyEmbed as publicClassName } from '../../public-classnames.js';
+import { mergeClassNames } from '../../utils/index.js';
+import cssModule from './styles.module.css';
+// `/intl-fr/track/ID` is the shape a shared link carries these days, hence the locale.
+function embedPath(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    const match = /^(?:\/intl-[a-z]{2})?\/(track|album|playlist|episode|show)\/([A-Za-z0-9]+)/v
+        .exec(url.pathname);
+    if (match === null)
+        return null;
+    return `${match[1]}/${match[2]}`;
+}
+/**
+ * A Spotify track, album, playlist, episode or show, embedded from its canonical URL.
+ *
+ * ### Root element modifiers
+ * - `--link` — nothing embeddable could be read, so a link is rendered instead.
+ *
+ * @param props - Component properties.
+ * @see {@link PlatformProps}
+ * @returns An `<iframe>` on `open.spotify.com/embed/…`, or an `<a>` on the URL as given.
+ */
+export const SpotifyEmbed = ({ className, url, title }) => {
+    const path = embedPath(url);
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null, { link: path === null }), className);
+    if (path === null)
+        return _jsx("a", { className: rootClss, href: url, children: title });
+    return _jsx("iframe", { className: rootClss, src: `https://open.spotify.com/embed/${path}`, title: title, loading: "lazy", allow: "autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture" });
+};

package/components/Embed/VimeoEmbed/index.d.ts

@@ -0,0 +1,14 @@
+import type { FunctionComponent } from 'react';
+import type { PlatformProps } from '../types.js';
+/**
+ * A Vimeo video, embedded from its canonical URL.
+ *
+ * ### Root element modifiers
+ * - `--link` — no video id could be read, so a link is rendered instead of a frame.
+ *
+ * @param props - Component properties.
+ * @see {@link PlatformProps}
+ * @returns An `<iframe>` on `player.vimeo.com/video/<id>`, or an `<a>` on the URL as
+ * given.
+ */
+export declare const VimeoEmbed: FunctionComponent<PlatformProps>;

package/components/Embed/VimeoEmbed/index.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { clss } from '@design-edito/tools/agnostic/css/clss/index.js';
+import { vimeoEmbed as publicClassName } from '../../public-classnames.js';
+import { mergeClassNames } from '../../utils/index.js';
+import cssModule from './styles.module.css';
+// The id is the last run of digits in the path — `/123`, `/video/123`, `/channels/x/123`.
+// An unlisted video carries a hash after it, which the player needs as `h`.
+function videoId(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    const match = /\/(\d+)(?:\/([A-Za-z0-9]+))?\/?$/v.exec(url.pathname);
+    if (match?.[1] === undefined)
+        return null;
+    return { id: match[1], hash: match[2] ?? null };
+}
+/**
+ * A Vimeo video, embedded from its canonical URL.
+ *
+ * ### Root element modifiers
+ * - `--link` — no video id could be read, so a link is rendered instead of a frame.
+ *
+ * @param props - Component properties.
+ * @see {@link PlatformProps}
+ * @returns An `<iframe>` on `player.vimeo.com/video/<id>`, or an `<a>` on the URL as
+ * given.
+ */
+export const VimeoEmbed = ({ className, url, title }) => {
+    const video = videoId(url);
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null, { link: video === null }), className);
+    if (video === null)
+        return _jsx("a", { className: rootClss, href: url, children: title });
+    const query = video.hash === null ? '' : `?h=${video.hash}`;
+    return _jsx("iframe", { className: rootClss, src: `https://player.vimeo.com/video/${video.id}${query}`, title: title, loading: "lazy", allow: "autoplay; fullscreen; picture-in-picture" });
+};

package/components/Embed/YoutubeEmbed/index.d.ts

@@ -0,0 +1,18 @@
+import type { FunctionComponent } from 'react';
+import type { PlatformProps } from '../types.js';
+/**
+ * A YouTube video, embedded from its canonical URL.
+ *
+ * ### Root element modifiers
+ * - `--link` — no video id could be read, so a link is rendered instead of a frame.
+ *
+ * @param props - Component properties.
+ * @see {@link PlatformProps}
+ * @returns An `<iframe>` on `youtube.com/embed/<id>`, or an `<a>` on the URL as given.
+ *
+ * @remarks
+ * `watch?v=`, `youtu.be/`, `/shorts/`, `/embed/`, `/live/` and `/v/` all carry an id.
+ * Anything else — a channel, a playlist URL, a search — has none to find, which is a
+ * state and not a failure: the component says so with a modifier and links out.
+ */
+export declare const YoutubeEmbed: FunctionComponent<PlatformProps>;

package/components/Embed/YoutubeEmbed/index.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { clss } from '@design-edito/tools/agnostic/css/clss/index.js';
+import { youtubeEmbed as publicClassName } from '../../public-classnames.js';
+import { mergeClassNames } from '../../utils/index.js';
+import cssModule from './styles.module.css';
+function videoId(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (url.hostname === 'youtu.be') {
+        const fromPath = url.pathname.slice(1).split('/')[0] ?? '';
+        return fromPath === '' ? null : fromPath;
+    }
+    const fromQuery = url.searchParams.get('v');
+    if (fromQuery !== null && fromQuery !== '')
+        return fromQuery;
+    return /^\/(?:shorts|embed|live|v)\/([^\/]+)/v.exec(url.pathname)?.[1] ?? null;
+}
+/**
+ * A YouTube video, embedded from its canonical URL.
+ *
+ * ### Root element modifiers
+ * - `--link` — no video id could be read, so a link is rendered instead of a frame.
+ *
+ * @param props - Component properties.
+ * @see {@link PlatformProps}
+ * @returns An `<iframe>` on `youtube.com/embed/<id>`, or an `<a>` on the URL as given.
+ *
+ * @remarks
+ * `watch?v=`, `youtu.be/`, `/shorts/`, `/embed/`, `/live/` and `/v/` all carry an id.
+ * Anything else — a channel, a playlist URL, a search — has none to find, which is a
+ * state and not a failure: the component says so with a modifier and links out.
+ */
+export const YoutubeEmbed = ({ className, url, title }) => {
+    const id = videoId(url);
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null, { link: id === null }), className);
+    if (id === null)
+        return _jsx("a", { className: rootClss, href: url, children: title });
+    return _jsx("iframe", { className: rootClss, src: `https://www.youtube.com/embed/${id}`, title: title, loading: "lazy", allow: "accelerometer; clipboard-write; encrypted-media; fullscreen; picture-in-picture" });
+};

package/components/Embed/index.d.ts

@@ -0,0 +1,44 @@
+import type { FunctionComponent } from 'react';
+import type { WithClassName } from '../utils/types.js';
+import { type EmbedPlatform } from './types.js';
+/**
+ * Props for the {@link Embed} component.
+ *
+ * @property url - The canonical URL, as a reader would have copied it. The host it names
+ * decides which player renders it.
+ * @property title - What the frame is called, for assistive technology, and the text of
+ * the link it falls back to.
+ * @property platform - Forces a player, for a URL whose host does not say which one it
+ * is — a custom domain, a shortener. Left out, the host decides.
+ */
+export type Props = WithClassName<{
+    url: string;
+    title: string;
+    platform?: EmbedPlatform;
+}>;
+/**
+ * A media URL, rendered by whichever player its host calls for.
+ *
+ * ### Root element modifiers
+ * - `--youtube`, `--spotify`, `--vimeo` — which player is rendering, one case out of a
+ *   few rather than a yes-or-no.
+ * - `--link` — the host is not one of {@link embedPlatforms}, so a link is rendered.
+ *
+ * ### CSS elements
+ * - `player` — the platform player, whichever it is. It carries its own public class
+ *   too, so a stylesheet can target every embed at once or one host in particular.
+ * - `link` — the fallback link, present only under `--link`.
+ *
+ * ### Data attributes on the root element
+ * - `data-platform` — the recognised host. Absent when there is none.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A `<div>` holding the platform player, or a link when no player fits.
+ *
+ * @remarks
+ * An unrecognised host is a state and not a failure: nothing throws and nothing is
+ * logged, the component renders the link and says so with a modifier. Same inside each
+ * player for a URL of the right host with no id to read.
+ */
+export declare const Embed: FunctionComponent<Props>;

package/components/Embed/index.js

@@ -0,0 +1,71 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { clss } from '@design-edito/tools/agnostic/css/clss/index.js';
+import { embed as publicClassName } from '../public-classnames.js';
+import { mergeClassNames } from '../utils/index.js';
+import { SpotifyEmbed } from './SpotifyEmbed/index.js';
+import { VimeoEmbed } from './VimeoEmbed/index.js';
+import { YoutubeEmbed } from './YoutubeEmbed/index.js';
+import { embedPlatforms } from './types.js';
+import cssModule from './styles.module.css';
+// WIP — no action or instruction surface yet. Whether a player is worth driving from the
+// outside (play, mute, a viewport behaviour) is a question for the day one of these hosts
+// gives us an API to drive it with; an iframe answers to nothing from here.
+const platformHostnames = {
+    youtube: [/(^|\.)youtube\.com$/v, /(^|\.)youtube-nocookie\.com$/v, /^youtu\.be$/v],
+    spotify: [/(^|\.)spotify\.com$/v],
+    vimeo: [/(^|\.)vimeo\.com$/v]
+};
+const platformEmbeds = {
+    youtube: YoutubeEmbed,
+    spotify: SpotifyEmbed,
+    vimeo: VimeoEmbed
+};
+function toPlatform(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    const found = embedPlatforms
+        .find(platform => platformHostnames[platform].some(hostname => hostname.test(url.hostname)));
+    return found ?? null;
+}
+/**
+ * A media URL, rendered by whichever player its host calls for.
+ *
+ * ### Root element modifiers
+ * - `--youtube`, `--spotify`, `--vimeo` — which player is rendering, one case out of a
+ *   few rather than a yes-or-no.
+ * - `--link` — the host is not one of {@link embedPlatforms}, so a link is rendered.
+ *
+ * ### CSS elements
+ * - `player` — the platform player, whichever it is. It carries its own public class
+ *   too, so a stylesheet can target every embed at once or one host in particular.
+ * - `link` — the fallback link, present only under `--link`.
+ *
+ * ### Data attributes on the root element
+ * - `data-platform` — the recognised host. Absent when there is none.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A `<div>` holding the platform player, or a link when no player fits.
+ *
+ * @remarks
+ * An unrecognised host is a state and not a failure: nothing throws and nothing is
+ * logged, the component renders the link and says so with a modifier. Same inside each
+ * player for a URL of the right host with no id to read.
+ */
+export const Embed = ({ className, url, title, platform }) => {
+    const resolved = platform ?? toPlatform(url);
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null, {
+        ...resolved === null ? {} : { [resolved]: true },
+        link: resolved === null
+    }), className);
+    const PlatformEmbed = resolved === null ? null : platformEmbeds[resolved];
+    return _jsx("div", { className: rootClss, "data-platform": resolved ?? undefined, children: PlatformEmbed === null
+            ? _jsx("a", { className: c('link'), href: url, children: title })
+            : _jsx(PlatformEmbed, { className: c('player'), url: url, title: title }) });
+};

package/components/Embed/types.d.ts

@@ -0,0 +1,22 @@
+import type { WithClassName } from '../utils/types.js';
+/**
+ * The platforms with a player of their own.
+ *
+ * An `as const` array rather than a union: recognising a URL's host is done against these
+ * values at runtime, and a consumer validating what it stores needs them too.
+ */
+export declare const embedPlatforms: readonly ["youtube", "spotify", "vimeo"];
+/** One of {@link embedPlatforms}. */
+export type EmbedPlatform = typeof embedPlatforms[number];
+/**
+ * What every platform player takes.
+ *
+ * @property url - The canonical URL, as a reader would have copied it. Each player cuts
+ * its own embed URL out of it.
+ * @property title - What the frame is called, for assistive technology, and the text of
+ * the link it falls back to.
+ */
+export type PlatformProps = WithClassName<{
+    url: string;
+    title: string;
+}>;

package/components/Embed/types.js

@@ -0,0 +1,7 @@
+/**
+ * The platforms with a player of their own.
+ *
+ * An `as const` array rather than a union: recognising a URL's host is done against these
+ * values at runtime, and a consumer validating what it stores needs them too.
+ */
+export const embedPlatforms = ['youtube', 'spotify', 'vimeo'];