npm - @janga/norna - Versions diffs - 0.7.18 → 0.7.22 - Mend

@janga/norna 0.7.18 → 0.7.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (595) hide show

package/docs/design/command-organization.md DELETED Viewed

@@ -1,414 +0,0 @@
-# Command Organization
-This document defines the naming principles for commands in `norna`, site
-repositories, and GitHub projects that embed a Norna site.
-The goal is that command names reveal both the action and the scope they affect.
-This matters because the same repository can contain a Norna site, an app, tests,
-and a publishing workflow that should not accidentally share ambiguous command
-names.
-## Situations
-`norna` commands must be understandable in three situations:
-- Standalone site project: the repository exists only to publish one
-  `norna` site.
-- Mixed project: the repository contains another project, such as an app or
-  library, and includes a Norna site as one part of its
-  GitHub Pages output.
-- Engine development: the repository is `norna` itself.
-## Namespaces
-Use these namespaces consistently.
-### `norna:*`
-Use `norna:*` npm scripts in repositories that consume `norna`.
-These scripts operate on a selected site source directory. In a standalone site
-project that directory is normally `site/`. In a mixed project it may be a more
-specific directory such as `presentation/`, with the script setting
-`NORNA_SITE_DIR` or passing `norna --site-dir`.
-Examples:
-```sh
-npm run norna:dev
-npm run norna:check
-npm run norna:sync
-npm run norna:build
-```
-Mixed projects must use `norna:*` for Norna work so names such as `build`,
-`test`, and `deploy` can remain under the containing project's control.
-Standalone site projects should also use `norna:*` as the primary documented
-interface. They may provide unprefixed aliases when the alias means the same
-thing for the whole repository, for example `npm run build` as an alias for
-`npm run norna:build`.
-### Direct CLI Shortcut
-Users may install `@janga/norna` globally as a cross-platform launcher and use
-`norna dev`, `norna check`, or `norna build`. The launcher must delegate to the
-current project's installed Norna version, so this shortcut does not replace
-the project dependency or its lockfile.
-### Project Commands That Call Norna Commands
-`norna` does not define a consuming project's unprefixed commands. Names
-such as `build`, `test`, and `deploy` belong to the project that consumes the
-Norna engine.
-Examples:
-```sh
-npm run build
-npm run test
-npm run deploy
-```
-When those project commands need the Norna site, they should call `norna:*`
-scripts instead of calling `norna` directly. That keeps the selected
-site source directory and other project-specific wrapper behavior in one
-place.
-In a mixed project, if `npm run build` exists, it should build the project's
-complete publishable artifact, not only the Norna site. If the project publishes a
-GitHub Pages artifact containing both a Norna site and an app, `build` should
-produce that full artifact and may call `npm run norna:build` internally.
-In a standalone site project, project commands may be aliases to `norna:*`
-commands because the Norna site is the whole project.
-### `release:*`
-Use `release:*` only in the engine repository.
-Examples:
-```sh
-npm run release:patch
-npm run release:minor
-npm run release:major
-```
-These commands change and publish the reusable `@janga/norna` package.
-They must not be part of ordinary site repositories.
-`npm run release:publish` is a low-level script used by the release command
-after the version has already been bumped. It is not the normal release entry
-point.
-### Direct CLI Commands
-The `norna` binary is the stable low-level command surface.
-Examples:
-```sh
-norna content:check
-norna content:sync
-norna build
-norna deploy
-```
-Npm scripts in site repositories are convenience wrappers around this binary.
-Documentation for ordinary site work should prefer the npm scripts because they
-can set the correct site directory for the repository.
-## Functional Groups
-### Install Norna Software
-Creating a new standalone site project starts outside the target project because
-the target does not have a `package.json` yet:
-```sh
-npx @janga/norna@latest init my-site
-cd my-site
-npm install
-```
-A mixed project already has its own repository and may have its own
-`package.json`. In that situation the Norna dependency should be installed as
-part of the existing project setup:
-```sh
-npm install --save-exact @janga/norna
-```
-The mixed project should then add `norna:*` scripts that point at the chosen
-site source directory.
-Engine development uses ordinary package installation in the engine repository:
-```sh
-npm install
-```
-### Upgrade Or Inspect Norna Software
-In a consuming repository, upgrading or inspecting the installed Norna engine
-is norna maintenance, so the preferred namespace is `norna:*`:
-```sh
-npm run norna:engine:version
-npm run norna:engine:update
-npm run norna:engine:update -- 0.2.0
-```
-These commands update the `@janga/norna` dependency and lockfile used by
-the repository. They do not release the engine package.
-In the engine repository, version changes belong to `release:*`:
-```sh
-npm run release:minor
-```
-### Initialize A Site Project Directory
-Initialization is a direct CLI operation because it usually happens before a
-project has npm scripts:
-```sh
-npx @janga/norna@latest init my-site
-```
-The initializer should support two setup modes that share the same `norna:*`
-command vocabulary.
-#### Standalone Setup
-Standalone setup creates a new project where the Norna site is the whole repository:
-```sh
-npx @janga/norna@latest init my-site --type standalone
-```
-This should be the default when the target is a new or empty directory.
-Standalone setup should create:
-- a normal site source directory, normally `site/`;
-- a `package.json` with `norna:*` scripts;
-- unprefixed convenience aliases only when they mean the same thing as the
-  whole project, for example `build` as an alias for `norna:build`;
-- the standard GitHub Pages workflow for publishing the site.
-#### Embedded Setup
-Embedded setup adds a Norna site to an existing project without taking ownership
-of that project's root commands:
-```sh
-npx @janga/norna@latest init . --type embedded --site-dir presentation
-```
-Embedded setup should be selected explicitly, or suggested when the target
-already contains a `package.json`.
-Embedded setup should create or update only the Norna-owned parts:
-- the chosen site source directory, for example `presentation/`;
-- `@janga/norna` as a project dependency;
-- `norna:*` scripts that set the selected site directory;
-- no unprefixed aliases such as `build`, `test`, `dev`, or `deploy`;
-- no project publishing workflow unless the caller explicitly asks for one.
-Embedded setup must not overwrite existing npm scripts without explicit user
-confirmation. If a needed `norna:*` script already exists, the initializer
-should report the conflict and let the user decide whether to replace it.
-### Control The Dev Server
-Norna dev-server commands belong under `norna:dev:*` in consuming
-repositories:
-```sh
-npm run norna:dev
-npm run norna:dev:lan
-npm run norna:dev:restart
-npm run norna:dev:status
-npm run norna:dev:logs
-npm run norna:dev:stop
-```
-The shorter `norna:dev` starts the normal local server. Subcommands manage
-the same server.
-In the engine repository, engine and example development may use the engine's own
-unprefixed commands:
-```sh
-npm run dev:local
-npm run dev:lan
-```
-### Test Configuration And Content
-Norna validation should use `norna:check` for the normal full check and
-more specific commands when a caller needs one part:
-```sh
-npm run norna:check
-npm run norna:config:check
-npm run norna:content:check
-```
-`norna:check` should run configuration and content checks in the order needed
-by the engine.
-Project-level tests remain project-owned commands:
-```sh
-npm run test
-```
-If a mixed project defines `test`, that command should cover the whole project.
-It may call `norna:check`, but it should not be a hidden synonym for only
-Norna validation.
-### Inspect Site Presentation
-Commands that inspect site presentation without changing source files use
-`norna:*` in consuming repositories:
-```sh
-npm run norna:typography:profiles
-npm run norna:typography:show
-```
-`norna:typography:profiles` shows the built-in typography profiles and rhythms
-from the installed engine. `norna:typography:show` shows the effective
-typography for the selected site after profiles, rhythms, and overrides have
-been applied.
-### Correct Content And Configuration
-Commands that modify Norna-owned source files use `norna:*`:
-```sh
-npm run norna:sync
-npm run norna:public
-npm run norna:images
-```
-`norna:sync` is the preferred npm wrapper for `norna content:sync`.
-Messages emitted by the engine should mention the direct CLI command and the
-starter-style npm wrapper when suggesting a fix.
-Configuration edits are normally manual edits to the selected site
-`config.yaml`, followed by:
-```sh
-npm run norna:config:check
-```
-### Build
-In a standalone site project:
-```sh
-npm run norna:build
-npm run norna:build:local
-npm run build
-```
-`norna:build:local` builds and restarts the local dev server. `build` may
-alias `norna:build` because the Norna site is the whole project.
-In a mixed project:
-```sh
-npm run norna:build
-npm run norna:build:local
-npm run build
-```
-`norna:build` builds only the Norna site. `norna:build:local` builds the
-site and restarts the local Norna dev server. If the mixed project defines
-`build`, that project command should build the complete publishable artifact,
-such as a GitHub Pages output that combines the Norna site with an app. It may call
-`norna:build` internally.
-In the engine repository:
-```sh
-npm run build
-npm run demo:build
-npm run test:fixture:build
-```
-Engine build commands verify the reusable package, fixtures, or demo site.
-### Publish
-Norna deploy helpers belong under `norna:deploy*` in consuming
-repositories:
-```sh
-npm run norna:deploy
-npm run norna:deploy:commit
-```
-Use these only when the Norna site is the deployable site or when the containing
-project deliberately delegates deployment to the Norna engine.
-Mixed projects may instead have project-owned deploy commands:
-```sh
-npm run deploy
-```
-Those commands should publish the complete project artifact. If they need the
-Norna site, they should call `norna:*` scripts internally.
-Engine publishing uses `release:*`, not `norna:*`:
-```sh
-npm run release:patch
-npm run release:minor
-npm run release:major
-```
-### Monitor Publishing
-GitHub Pages monitoring for a Norna site belongs under:
-```sh
-npm run norna:deploy:watch
-```
-Mixed projects may provide a project-owned monitoring command when monitoring
-is not specific to the Norna site:
-```sh
-npm run deploy:watch
-```
-That command should monitor the whole project's publishing workflow. If it needs
-norna-specific deploy settings, it should call `norna:deploy:watch`.
-## Naming Rules
-- Use `norna:*` for every npm script in a consuming repository whose direct
-  object is the Norna site, its source files, its generated images, its dev server,
-  or its engine dependency.
-- `norna` does not define unprefixed project commands such as `build`,
-  `test`, and `deploy` in consuming repositories.
-- If project commands need Norna behavior, they should call `norna:*`
-  scripts.
-- In standalone site projects, unprefixed project commands may alias `norna:*`
-  commands.
-- In mixed projects, unprefixed project commands must not be aliases for only
-  the Norna site unless the command name makes that scope explicit.
-- Use `release:*` only for publishing the reusable engine package.
-- Prefer direct `norna ...` commands in engine docs and diagnostics;
-  prefer npm scripts in site-repository docs.
-- Do not create separate namespaces for every internal concept. If a command is
-  about maintaining the Norna dependency in a consuming repository, keep it
-  under `norna:*`.

package/docs/design/navigation-and-theme-plan.md DELETED Viewed

@@ -1,186 +0,0 @@
-# Navigation And Theme Plan
-This document records the intended order of work for page hierarchy,
-navigation, and theme presets. It is an implementation plan, not a description
-of released behavior.
-## Goal
-Norna should support sites with limited global navigation and a larger local
-page hierarchy without making mobile navigation harder to understand. Theme
-presets should provide a coherent visual system without changing the site's
-information architecture.
-## Working Principles
-- The file structure defines the page hierarchy and presentation order.
-- Navigation behavior and navigation styling are separate concerns.
-- Global site navigation, local page navigation, and headings on the current
-  page have distinct roles.
-- Changing a theme preset must not change which pages are available or how the
-  page hierarchy is interpreted.
-- Site-wide visual identity should remain coherent while individual pages may
-  vary where that does not disrupt navigation or orientation.
-- Documentation and broad example migration should follow implementation and
-  manual evaluation, not precede them.
-## Order Of Work
-### 1. Stabilize The Page Tree - Complete
-Finish and test nested page discovery independently of final navigation
-presentation. Establish deterministic rules for:
-- directory parsing, page ids, URL paths, and presentation order;
-- parent and ancestor relationships;
-- collisions and invalid nesting;
-- page-local content, images, and themes;
-- breadcrumbs and current-branch discovery.
-Commit this foundation separately before broad theme or preset changes.
-The page tree now supports nested pages with deterministic directory parsing,
-URLs, ordering, ancestry, breadcrumbs, inherited page resources, and collision
-diagnostics.
-The current breaking page-container proof of concept removes the special root
-page. Every page now uses the same physical model:
-```text
-site/pages/NNN-page-id/
-  content.md
-  theme.yaml       # optional page-local presentation
-  images/          # optional managed page images
-  pages/           # optional child pages
-```
-`site/pages/000-home/content.md` is required and maps to `/`. The `000` prefix
-is reserved for this page. Other top-level page directories are its siblings,
-not its children. The homepage cannot contain a `pages/` hierarchy; place each
-top-level area beside `000-home` and nest further pages below that area.
-The root `site/` directory now contains only site-wide files and the page
-container. Removed root-level page and image locations produce a migration
-error instead of being interpreted as a second page model.
-### 2. Define The Navigation Contract - Complete
-The accepted information architecture is:
-- a small global navigation for the site's top-level areas;
-- a larger local page tree for the selected area;
-- breadcrumbs for location and ancestry;
-- headings for the current page integrated below that page in the local tree;
-- one unified mobile navigation containing the whole page hierarchy and the
-  current page headings.
-Navigation modes follow the site structure:
-- a single-page site uses section navigation;
-- an ordinary shallow multi-page site uses top navigation;
-- a deeper documentation-style hierarchy uses tree navigation.
-The tree contract is:
-- top-level areas remain available in the sticky global navigation;
-- the selected top-level area supplies the desktop local tree;
-- breadcrumbs show page ancestry without changing the vertical position of
-  the page heading;
-- a closed expandable page title expands the node without navigating;
-- an open expandable page title links to that page, while its chevron can
-  collapse the node;
-- a page without headings or child pages is always a direct link;
-- headings on the current page appear under its page node rather than in a
-  separate `On this page` region;
-- opening one branch does not implicitly close another branch;
-- long desktop trees scroll independently of short page content;
-- mobile uses one drawer for the complete hierarchy instead of requiring a
-  separate page-selection and section-selection sequence.
-Real links and native disclosure elements provide the fallback. JavaScript
-preserves explicitly opened branches, restores navigation scroll position,
-enhances focus handling, and keeps measured sticky offsets stable. Without
-JavaScript, navigation remains usable but manually opened branches are not
-preserved across page loads.
-The contract should also define the fallback and override behavior for the
-supported navigation modes. Structural behavior belongs to site-level engine
-configuration or deterministic automatic selection, not to presentation
-presets.
-The contract was evaluated with the nested-pages fixture and focused desktop,
-mobile, no-JavaScript, spatial-stability, and long-navigation tests.
-### 3. Implement Navigation In Layers - Complete
-Implement and verify the navigation model in this order:
-1. page-tree data and validation;
-2. desktop global navigation, local tree, breadcrumbs, and `On this page`;
-3. unified mobile navigation;
-4. keyboard, focus, current-page, and progressive-enhancement behavior;
-5. visual evaluation at representative viewport sizes.
-Real links remain the foundation. Client-side JavaScript is limited to
-interaction and state that cannot be retained adequately with HTML and CSS.
-### 4. Refine Theme And Preset Responsibilities - Proof Of Concept
-Presets should control visual presentation, including:
-- color system;
-- typography;
-- spacing and density;
-- page and content widths;
-- the visual treatment of global navigation, local navigation, breadcrumbs,
-  and `On this page`.
-Presets must not determine page hierarchy, link membership, or semantic
-navigation structure. Those must remain stable when a preset changes.
-Site-wide color, typography, and navigation treatment should normally remain
-consistent. Page-local theme variation should be limited to properties such as
-content width, density, and media presentation when variation does not weaken
-site identity or navigation clarity.
-The proof-of-concept contract is:
-- `config.yaml` owns the site-wide navigation mode;
-- the root `theme.yaml` owns presets, palette, shape, typography, the page
-  frame, global spacing primitives, and default page presentation;
-- a page-local `theme.yaml` may set only `layout.textWidth`,
-  `layout.contentSpacing`, managed-image sizing, and
-  `sections.backgroundPattern`;
-- page-local values are inherited by descendant pages and merged field by
-  field, while global visual identity is never replaced;
-- `layout.contentSpacing` replaces the ambiguous `layout.density` name;
-- `sections.backgroundPattern` replaces the low-level `sectionSurfaces` list
-  with `uniform`, `alternating`, and `cycling` choices;
-- custom presets and custom font definitions are deferred until the built-in
-  contract has been tested in real sites.
-The nested-pages fixture is the current proof of concept. The engine-owned
-basic init starter follows the new page contract so newly created sites remain
-valid. Documentation, other starters, and broad examples should be migrated
-only after manual approval.
-### 5. Migrate After Evaluation
-After the page tree, navigation contract, and preset boundaries have been
-manually evaluated:
-- migrate fixtures and examples;
-- update schemas and editor assistance;
-- update Markdown reference documentation;
-- update the rendered documentation site;
-- remove obsolete navigation and preset behavior rather than retaining
-  compatibility layers.
-Keep foundation, navigation, preset, migration, and documentation changes in
-separate commits where practical.
-## Immediate Checkpoint
-The nested navigation contract has been evaluated and committed. The unified
-page-container and theme-scope proof of concepts are now ready for manual
-evaluation against the nested-pages fixture before broad migration begins.