@vit-foundation/ui 0.2.1 → 0.3.0

package/README.md

@@ -1,116 +1,70 @@
 # @vit-foundation/ui
 
 Fundació VIT's shared Svelte 5 component library: the components behind
-[fundaciovit.org](https://fundaciovit.org), decoupled from any one app, with an
-optional **edit mode** that lets a CMS-shaped consumer make the rendered
+[fundaciovit.org](https://fundaciovit.org), decoupled from any one app, with
+an optional **edit mode** that lets a CMS-shaped consumer make the rendered
 content editable in place.
 
 ```sh
 npm install @vit-foundation/ui
 ```
 
-Requires `svelte` ^5.0.0 as a peer.
-
-## Quick start
-
-```svelte
-<script>
-	import { WeeklieCard, PageShell } from '@vit-foundation/ui';
-	import '@vit-foundation/ui/tokens.css'; // design tokens (CSS custom properties)
-	import '@vit-foundation/ui/base.css'; // utility classes + edit affordance
-</script>
-
-<PageShell title="Weeklies">
-	<WeeklieCard weekly={data.weekly} />
-</PageShell>
-```
-
-Every component renders standalone with Catalan copy and identity hrefs.
-Subpath imports are available when you want a narrower graph:
-`@vit-foundation/ui/ui`, `/layout`, `/weeklies`, `/projects`, `/team`,
-`/timeline`, `/jobs`, `/edit`, `/config`.
-
-## Wiring a host app: `UiProvider`
-
-Strings, href resolution, the active locale, and the current URL come from a
-`UiConfig` context. Mount it once, in the root layout. The foundation website
-wires it to Paraglide and SvelteKit like this:
+Requires `svelte` ^5.0.0 as a peer. Import the two stylesheets once:
 
 ```svelte
 <script>
-	import { UiProvider } from '@vit-foundation/ui';
-	import { page } from '$app/state';
-	import { m } from '$lib/paraglide/messages';
-	import { getLocale, locales, deLocalizeUrl } from '$lib/paraglide/runtime';
+	import '@vit-foundation/ui/tokens.css';
+	import '@vit-foundation/ui/base.css';
 </script>
-
-<UiProvider
-	config={{
-		href: (path, options) => localizeHref(path, options),
-		locale: () => getLocale(),
-		locales,
-		url: () => page.url,
-		canonicalPathname: (url) => deLocalizeUrl(url).pathname,
-		siteName: 'ViT',
-		messages: m
-	}}
->
-	{@render children()}
-</UiProvider>
-```
-
-`locale`, `url`, and `messages` reads are lazy, so reactive sources flow
-through: a locale switch re-renders every consumer without a remount.
-`messages` is a typed structural subset of a Paraglide `m` module — pass it
-wholesale. Keys consumed only through this package still count as used;
-don't prune them from your message catalogue.
-
-## Edit mode
-
-Components render plain, already-localized strings. To make one editable,
-pass an _edit descriptor_ naming what the string is — and install an
-`EditAdapter` that knows how to persist it. No adapter (or `isEditing`
-off) means every descriptor is inert and the render is byte-identical to
-the read-only one. **The package never talks to a database.**
-
-```svelte
-<script>
-	import { setEditAdapter, entityEdit, WeeklieCard } from '@vit-foundation/ui';
-
-	let editing = $state(false);
-
-	setEditAdapter({
-		get isEditing() {
-			return editing;
-		},
-		// Merge { [descriptor.locale]: value } into the localized column.
-		// Reject when persistence fails — the editor keeps the draft and
-		// shows the error state. Never let a save empty the canonical `ca`.
-		save: (descriptor, value) => saveContent(descriptor, value)
-	});
-
-	const edit = entityEdit('weeklies', weekly.id, 'ca');
-</script>
-
-<WeeklieCard {weekly} edit={{ title: edit('title'), excerpt: edit('excerpt') }} />
-```
-
-Editing UX: click into an outlined text, type, and blur or press Enter to
-save (Cmd/Ctrl+Enter for multiline fields, Escape reverts). `RichText`
-opens a source editor over the block mini-format with a live preview.
-Wrap your own render sites with the `Editable` primitive:
-
-```svelte
-<Editable edit={pageCopyEdit('home', 'hero_title', 'ca')} value={copy.hero_title}>
-	{#snippet children(text, attrs)}
-		<h1 {...attrs}>{text}</h1>
-	{/snippet}
-</Editable>
 ```
 
-The `content` types (`LocalizedText`, `ContentRef`, …) mirror the
-foundation's content model: localized text is a per-locale record whose
-Catalan value is canonical and required.
+## The library at a glance
+
+Everything exports flat from the root, and again grouped by role:
+
+| Entry point                                                     | What lives there                                                                                                                                                                      |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`/primitives`](./docs/components/primitives.md)                | Button, GhostButton, Link, CardMedia, CardTitle, CopyIntro, DateText, DecorShapes, FilterChips, Pagination, RichText, SearchInput, ShareRow                                           |
+| [`/forms`](./docs/forms.md)                                     | Field, FormFeedback, FormErrorFeedback, FormResultSlot, Honeypot, LocaleField, NewsletterIntentField — plus the remote-form seam: structural types, transport constants, field bounds |
+| [`/chrome`](./docs/components/chrome.md)                        | PageShell, Nav, Footer                                                                                                                                                                |
+| [`/content`](./docs/components/content.md)                      | WeeklieCard, ProjectCard, Timeline, TimelineMilestone, TeamMemberCard, CollaboratorList, JobList, SortSelect — plus the data shapes and helpers                                       |
+| [`/community`](./docs/components/community.md)                  | AuthPageShell, LoginForm, SignupForm, GoogleAuthForm, AccountPanel, NewsletterSignup, CommentSection, ReactionBar, ContactForm                                                        |
+| [`/edit`](./docs/edit-mode.md)                                  | Editable, setEditAdapter/getEditAdapter, descriptors and helpers, LocalizedText                                                                                                       |
+| [`/config`](./docs/getting-started.md#wiring-an-app-uiprovider) | UiProvider, UiConfig, the locale set, the default Catalan messages                                                                                                                    |
+| `/testing`                                                      | createRemoteFormMock — the remote-form stand-in for stories and tests                                                                                                                 |
+
+Every component renders standalone (Catalan copy, identity hrefs); an app
+integrates its i18n and router through one `UiProvider` in the root layout.
+
+## Documentation
+
+- **[Getting started](./docs/getting-started.md)** — install, styles, entry
+  points, wiring `UiProvider` (with the foundation website's Paraglide +
+  SvelteKit example)
+- **[Edit mode](./docs/edit-mode.md)** — descriptors, the `EditAdapter`
+  contract, the `Editable` primitive, the editing UX, the save semantics
+- **[Forms](./docs/forms.md)** — the remote-form seam: passing preflighted
+  forms in, keyed factories, the shared constants, the form building blocks
+- **[Theming](./docs/theming.md)** — the design tokens and the base utilities
+- **Component reference** — [primitives](./docs/components/primitives.md) ·
+  [chrome](./docs/components/chrome.md) ·
+  [content](./docs/components/content.md) ·
+  [community](./docs/components/community.md)
+- **Storybook** — `npm run storybook`: every component has a story;
+  `Edit mode/EditMode` demos the whole editing loop against an in-memory
+  adapter
+
+## Two design rules worth knowing before anything else
+
+1. **The package never talks to a backend.** Content arrives as props; edits
+   leave through an injected `EditAdapter`; remote forms are passed in
+   preflighted by the host against its own schemas. An app that injects
+   nothing gets a read-only render, byte-identical to a build with no edit
+   mode at all.
+2. **Shared constants have one owner.** The honeypot field name, the
+   newsletter-intent encoding, and the field bounds export from `./forms`;
+   host apps import them into their schemas so markup and server envelope
+   can never drift apart.
 
 ## Development
 
@@ -122,8 +76,12 @@ npm run check && npm run lint && npm run test:unit -- --run
 npm run build      # svelte-package + publint
 ```
 
-Stories live in `src/lib/components/stories/<group>/`, component tests in
-`src/lib/components/tests/<group>/`, mirroring the component tree.
+Internally, components live in `src/lib/components/<website-group>/` with
+stories in `components/stories/<group>/` and tests in
+`components/tests/<group>/` — the layout they had in fndvit-website, kept
+diffable against history. The public structure is the semantic entry points
+above, assembled in `src/lib/{primitives,chrome,content-components,community}.ts`
+and `src/lib/forms/index.ts`.
 
 Releases: bump with `npm version`, push the `v*` tag, and the release
-workflow publishes to npm.
+workflow publishes to npm (requires the `NPM_TOKEN` secret).

package/dist/chrome.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Site chrome: the shell every page renders through, and the header/footer
+ * pair. Nav and Footer take the same SiteLink[] so the two can never drift.
+ */
+export { default as Footer } from './components/layout/Footer.svelte';
+export { default as Nav } from './components/layout/Nav.svelte';
+export { default as PageShell } from './components/layout/PageShell.svelte';

package/dist/chrome.js

@@ -0,0 +1,7 @@
+/**
+ * Site chrome: the shell every page renders through, and the header/footer
+ * pair. Nav and Footer take the same SiteLink[] so the two can never drift.
+ */
+export { default as Footer } from './components/layout/Footer.svelte';
+export { default as Nav } from './components/layout/Nav.svelte';
+export { default as PageShell } from './components/layout/PageShell.svelte';

package/dist/community.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The server-flow components: auth, account, newsletter, comments, reactions
+ * and contact. Every one takes its remote form(s) as required props — the
+ * host app owns schemas and preflight; see ./forms for the seam's types.
+ */
+export * from './components/account/index.js';
+export * from './components/auth/index.js';
+export * from './components/contact/index.js';
+export { default as CommentSection } from './components/weeklies/CommentSection.svelte';
+export type { CommentFormInstance } from './components/weeklies/CommentSection.svelte';
+export { default as ReactionBar } from './components/weeklies/ReactionBar.svelte';
+export type { CommentReactionChip, ReactionBarForms, WeeklyReactionChip } from './components/weeklies/ReactionBar.svelte';

package/dist/community.js

@@ -0,0 +1,10 @@
+/**
+ * The server-flow components: auth, account, newsletter, comments, reactions
+ * and contact. Every one takes its remote form(s) as required props — the
+ * host app owns schemas and preflight; see ./forms for the seam's types.
+ */
+export * from './components/account/index.js';
+export * from './components/auth/index.js';
+export * from './components/contact/index.js';
+export { default as CommentSection } from './components/weeklies/CommentSection.svelte';
+export { default as ReactionBar } from './components/weeklies/ReactionBar.svelte';

package/dist/content-components.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Content renderers: the components that present database content — cards,
+ * the timeline, listings. All prop-driven, all edit-mode capable, plus the
+ * structural data shapes they consume.
+ */
+export { default as CollaboratorList } from './components/team/CollaboratorList.svelte';
+export { default as JobList } from './components/jobs/JobList.svelte';
+export type { JobEditMap } from './components/jobs/JobList.svelte';
+export { default as ProjectCard } from './components/projects/ProjectCard.svelte';
+export type { ProjectEditMap } from './components/projects/ProjectCard.svelte';
+export { default as SortSelect } from './components/weeklies/SortSelect.svelte';
+export { default as TeamMemberCard } from './components/team/TeamMemberCard.svelte';
+export type { TeamMemberEditMap } from './components/team/TeamMemberCard.svelte';
+export { default as Timeline } from './components/timeline/Timeline.svelte';
+export { default as TimelineMilestone } from './components/timeline/TimelineMilestone.svelte';
+export type { MilestoneEditMap } from './components/timeline/TimelineMilestone.svelte';
+export { default as WeeklieCard } from './components/weeklies/WeeklieCard.svelte';
+export type { WeeklyEditMap } from './components/weeklies/WeeklieCard.svelte';
+export * from './content/index.js';
+export { MILESTONE_CATEGORY_COLOR, milestoneCategoryLabel } from './utils/milestones.js';
+export { contactCategoryLabel } from './utils/contact.js';
+export { formatDate, yearOf } from './utils/dates.js';

package/dist/content-components.js

@@ -0,0 +1,17 @@
+/**
+ * Content renderers: the components that present database content — cards,
+ * the timeline, listings. All prop-driven, all edit-mode capable, plus the
+ * structural data shapes they consume.
+ */
+export { default as CollaboratorList } from './components/team/CollaboratorList.svelte';
+export { default as JobList } from './components/jobs/JobList.svelte';
+export { default as ProjectCard } from './components/projects/ProjectCard.svelte';
+export { default as SortSelect } from './components/weeklies/SortSelect.svelte';
+export { default as TeamMemberCard } from './components/team/TeamMemberCard.svelte';
+export { default as Timeline } from './components/timeline/Timeline.svelte';
+export { default as TimelineMilestone } from './components/timeline/TimelineMilestone.svelte';
+export { default as WeeklieCard } from './components/weeklies/WeeklieCard.svelte';
+export * from './content/index.js';
+export { MILESTONE_CATEGORY_COLOR, milestoneCategoryLabel } from './utils/milestones.js';
+export { contactCategoryLabel } from './utils/contact.js';
+export { formatDate, yearOf } from './utils/dates.js';

package/dist/forms/index.d.ts

@@ -1,3 +1,10 @@
+export { default as Field } from '../components/ui/Field.svelte';
+export { default as FormErrorFeedback } from '../components/ui/FormErrorFeedback.svelte';
+export { default as FormFeedback } from '../components/ui/FormFeedback.svelte';
+export { default as FormResultSlot } from '../components/ui/FormResultSlot.svelte';
+export { default as Honeypot } from '../components/ui/Honeypot.svelte';
+export { default as LocaleField } from '../components/ui/LocaleField.svelte';
+export { default as NewsletterIntentField } from '../components/ui/NewsletterIntentField.svelte';
 export { COMMENT_BODY, CONTACT_MESSAGE, CONTACT_NAME, DISPLAY_NAME, EMAIL, LOGIN_PASSWORD, PASSWORD } from './constraints.js';
 export { hasNewsletterIntent, HONEYPOT_FIELD, isNewsletterIntent, NEWSLETTER_INTENT_PARAM, NEWSLETTER_INTENT_VALUE, withNewsletterIntent } from './transport.js';
 export type { FormFail, FormFieldIssue, FormResultLike, FormResultOf, KeyedRemoteForms, RemoteField, RemoteFormAttributes, RemoteFormInstance } from './types.js';

package/dist/forms/index.js

@@ -1,2 +1,9 @@
+export { default as Field } from '../components/ui/Field.svelte';
+export { default as FormErrorFeedback } from '../components/ui/FormErrorFeedback.svelte';
+export { default as FormFeedback } from '../components/ui/FormFeedback.svelte';
+export { default as FormResultSlot } from '../components/ui/FormResultSlot.svelte';
+export { default as Honeypot } from '../components/ui/Honeypot.svelte';
+export { default as LocaleField } from '../components/ui/LocaleField.svelte';
+export { default as NewsletterIntentField } from '../components/ui/NewsletterIntentField.svelte';
 export { COMMENT_BODY, CONTACT_MESSAGE, CONTACT_NAME, DISPLAY_NAME, EMAIL, LOGIN_PASSWORD, PASSWORD } from './constraints.js';
 export { hasNewsletterIntent, HONEYPOT_FIELD, isNewsletterIntent, NEWSLETTER_INTENT_PARAM, NEWSLETTER_INTENT_VALUE, withNewsletterIntent } from './transport.js';

package/dist/index.d.ts

@@ -1,18 +1,8 @@
-export * from './components/account/index.js';
-export * from './components/auth/index.js';
-export * from './components/contact/index.js';
-export * from './components/ui/index.js';
-export * from './components/layout/index.js';
-export * from './components/weeklies/index.js';
-export * from './components/projects/index.js';
-export * from './components/team/index.js';
-export * from './components/timeline/index.js';
-export * from './components/jobs/index.js';
+export * from './primitives.js';
+export * from './chrome.js';
+export * from './content-components.js';
+export * from './community.js';
 export * from './forms/index.js';
 export * from './config/index.js';
 export * from './edit/index.js';
-export * from './content/index.js';
-export { formatDate, yearOf } from './utils/dates.js';
-export { contactCategoryLabel } from './utils/contact.js';
-export { MILESTONE_CATEGORY_COLOR, milestoneCategoryLabel } from './utils/milestones.js';
 export { isPathUnder } from './utils/paths.js';

package/dist/index.js

@@ -1,23 +1,15 @@
-// Components, by group.
-export * from './components/account/index.js';
-export * from './components/auth/index.js';
-export * from './components/contact/index.js';
-export * from './components/ui/index.js';
-export * from './components/layout/index.js';
-export * from './components/weeklies/index.js';
-export * from './components/projects/index.js';
-export * from './components/team/index.js';
-export * from './components/timeline/index.js';
-export * from './components/jobs/index.js';
-// The form seam: structural remote-form types, transport constants, field bounds.
+// The whole surface, flat — importable piecemeal through the semantic
+// subpaths: ./primitives, ./forms, ./chrome, ./content, ./community,
+// ./edit, ./config, ./testing.
+export * from './primitives.js';
+export * from './chrome.js';
+export * from './content-components.js';
+export * from './community.js';
+// The form seam: form components, structural remote-form types, transport
+// constants, field bounds.
 export * from './forms/index.js';
 // App wiring: configuration context and the edit-mode contract.
 export * from './config/index.js';
 export * from './edit/index.js';
-// Content shapes and the rich-text mini-format.
-export * from './content/index.js';
-// Utilities the components share with their host apps.
-export { formatDate, yearOf } from './utils/dates.js';
-export { contactCategoryLabel } from './utils/contact.js';
-export { MILESTONE_CATEGORY_COLOR, milestoneCategoryLabel } from './utils/milestones.js';
+// Path utility shared with host apps.
 export { isPathUnder } from './utils/paths.js';

package/dist/primitives.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Generic UI atoms: buttons, cards, text, media, list controls. Domain-free —
+ * everything here renders whatever it is handed.
+ */
+export { default as Button } from './components/ui/Button.svelte';
+export { default as CardMedia } from './components/ui/CardMedia.svelte';
+export { default as CardTitle } from './components/ui/CardTitle.svelte';
+export { default as CopyIntro } from './components/ui/CopyIntro.svelte';
+export { default as DateText } from './components/ui/DateText.svelte';
+export { default as DecorShapes } from './components/ui/DecorShapes.svelte';
+export { default as FilterChips } from './components/ui/FilterChips.svelte';
+export { default as GhostButton } from './components/ui/GhostButton.svelte';
+export { default as Link } from './components/ui/Link.svelte';
+export { default as Pagination } from './components/ui/Pagination.svelte';
+export { default as RichText } from './components/ui/RichText.svelte';
+export { default as SearchInput } from './components/ui/SearchInput.svelte';
+export { default as ShareRow } from './components/ui/ShareRow.svelte';

package/dist/primitives.js

@@ -0,0 +1,17 @@
+/**
+ * Generic UI atoms: buttons, cards, text, media, list controls. Domain-free —
+ * everything here renders whatever it is handed.
+ */
+export { default as Button } from './components/ui/Button.svelte';
+export { default as CardMedia } from './components/ui/CardMedia.svelte';
+export { default as CardTitle } from './components/ui/CardTitle.svelte';
+export { default as CopyIntro } from './components/ui/CopyIntro.svelte';
+export { default as DateText } from './components/ui/DateText.svelte';
+export { default as DecorShapes } from './components/ui/DecorShapes.svelte';
+export { default as FilterChips } from './components/ui/FilterChips.svelte';
+export { default as GhostButton } from './components/ui/GhostButton.svelte';
+export { default as Link } from './components/ui/Link.svelte';
+export { default as Pagination } from './components/ui/Pagination.svelte';
+export { default as RichText } from './components/ui/RichText.svelte';
+export { default as SearchInput } from './components/ui/SearchInput.svelte';
+export { default as ShareRow } from './components/ui/ShareRow.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vit-foundation/ui",
-	"version": "0.2.1",
+	"version": "0.3.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",
@@ -37,55 +37,30 @@
 			"svelte": "./dist/index.js",
 			"default": "./dist/index.js"
 		},
-		"./ui": {
-			"types": "./dist/components/ui/index.d.ts",
-			"svelte": "./dist/components/ui/index.js",
-			"default": "./dist/components/ui/index.js"
+		"./primitives": {
+			"types": "./dist/primitives.d.ts",
+			"svelte": "./dist/primitives.js",
+			"default": "./dist/primitives.js"
 		},
-		"./auth": {
-			"types": "./dist/components/auth/index.d.ts",
-			"svelte": "./dist/components/auth/index.js",
-			"default": "./dist/components/auth/index.js"
-		},
-		"./account": {
-			"types": "./dist/components/account/index.d.ts",
-			"svelte": "./dist/components/account/index.js",
-			"default": "./dist/components/account/index.js"
-		},
-		"./contact": {
-			"types": "./dist/components/contact/index.d.ts",
-			"svelte": "./dist/components/contact/index.js",
-			"default": "./dist/components/contact/index.js"
-		},
-		"./layout": {
-			"types": "./dist/components/layout/index.d.ts",
-			"svelte": "./dist/components/layout/index.js",
-			"default": "./dist/components/layout/index.js"
-		},
-		"./weeklies": {
-			"types": "./dist/components/weeklies/index.d.ts",
-			"svelte": "./dist/components/weeklies/index.js",
-			"default": "./dist/components/weeklies/index.js"
-		},
-		"./projects": {
-			"types": "./dist/components/projects/index.d.ts",
-			"svelte": "./dist/components/projects/index.js",
-			"default": "./dist/components/projects/index.js"
+		"./forms": {
+			"types": "./dist/forms/index.d.ts",
+			"svelte": "./dist/forms/index.js",
+			"default": "./dist/forms/index.js"
 		},
-		"./team": {
-			"types": "./dist/components/team/index.d.ts",
-			"svelte": "./dist/components/team/index.js",
-			"default": "./dist/components/team/index.js"
+		"./chrome": {
+			"types": "./dist/chrome.d.ts",
+			"svelte": "./dist/chrome.js",
+			"default": "./dist/chrome.js"
 		},
-		"./timeline": {
-			"types": "./dist/components/timeline/index.d.ts",
-			"svelte": "./dist/components/timeline/index.js",
-			"default": "./dist/components/timeline/index.js"
+		"./content": {
+			"types": "./dist/content-components.d.ts",
+			"svelte": "./dist/content-components.js",
+			"default": "./dist/content-components.js"
 		},
-		"./jobs": {
-			"types": "./dist/components/jobs/index.d.ts",
-			"svelte": "./dist/components/jobs/index.js",
-			"default": "./dist/components/jobs/index.js"
+		"./community": {
+			"types": "./dist/community.d.ts",
+			"svelte": "./dist/community.js",
+			"default": "./dist/community.js"
 		},
 		"./edit": {
 			"types": "./dist/edit/index.d.ts",
@@ -97,11 +72,6 @@
 			"svelte": "./dist/config/index.js",
 			"default": "./dist/config/index.js"
 		},
-		"./forms": {
-			"types": "./dist/forms/index.d.ts",
-			"svelte": "./dist/forms/index.js",
-			"default": "./dist/forms/index.js"
-		},
 		"./testing": {
 			"types": "./dist/testing/remote-form.d.ts",
 			"svelte": "./dist/testing/remote-form.js",
@@ -152,7 +122,7 @@
 		"svelte"
 	],
 	"license": "MIT",
-	"description": "Fundació VIT's shared Svelte 5 component library with pluggable edit mode",
+	"description": "Fundaci\u00f3 VIT's shared Svelte 5 component library with pluggable edit mode",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/fndvit/VizVit-UI.git"