@fractaldesign/fractalstyler 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Amritanshu Pandey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# Fractalstyler
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A composition styling system — the class registry is the public API: compose
+in markup, write no stylesheet. Ships as editable SASS and as plain compiled
+CSS. MIT © [Fractal Mandala](https://github.com/fractalmandala)
+
+**This library is a work in constant progress and breaking changes each bump.**
+
+- Registry: [`REGISTRY.md`](REGISTRY.md) · [`docs/REGISTRY.api.md`](docs/REGISTRY.api.md)
+- Configuration, the *why/how*: [`docs/references/configurations.md`](docs/references/configurations.md) · the *what*: [`docs/references/configurations-api.md`](docs/references/configurations-api.md)
+- Agent skill: [`skills/fractal-styler/SKILL.md`](skills/fractalstyler/SKILL.md)
+
+---
+
+## Using it in a project
+
+Two ways to hold the styles, and an IDE layer you can add to either.
+
+### 1. Install and use — track the package; upgrades come from npm
+
+```sh
+pnpm add -D @fractaldesign/fractalstyler
+```
+
+```sass
+@use '@fractaldesign/fractalstyler/styles' as *
+```
+
+Plain CSS consumers need no SASS toolchain:
+
+```js
+import '@fractaldesign/fractalstyler/css'; // dist/css/fractalstyler.css
+```
+
+The classes are active once the import is in place. To keep the registry and
+the configuration docs greppable inside your project, run:
+
+```sh
+npx @fractaldesign/fractalstyler init --track --docs
+```
+
+which places `REGISTRY.md`, `REGISTRY.api.md` and
+`references/configurations{,-api}.md` into a `fractalstyler/` folder at your
+project root (`--docs-dir` to choose another). Docs are snapshots — re-run
+`init` after upgrading to refresh them.
+
+### 2. Eject — the files become yours
+
+Copies every styles layer, the palette modules and the registry builder into
+your project, where you may edit them freely (including the `$`-variables in
+`_00_config.sass`, in place):
+
+```sh
+npx @fractaldesign/fractalstyler eject
+```
+
+That leaves you `src/lib/styles/` (11 layers + a seeded `_09_own.sass`),
+`src/lib/palette/`, and `scripts/build-registry.mjs`. Import your local tree,
+regenerate your own registry after edits (`node scripts/build-registry.mjs`,
+Node only), and the linter keeps enforcing the contract against your copy:
+
+```sh
+npx @fractaldesign/fractalstyler lint src/
+```
+
+Nothing existing is ever overwritten — on a name conflict your file is kept
+and reported. Delete a kept file and re-run `eject` to re-place it.
+
+> **Drift warning**: an ejected copy no longer tracks the package — upgrades
+> stop coming from npm. This is the less advisable mode; it exists so a
+> project that must own its styles can still start from the whole system.
+
+### 3. Either mode, with or without the IDE extension
+
+Both `init` and `eject` accept `--intellisense` / `--no-intellisense`. With it
+on, the CLI writes the workspace settings read by the
+[Styles IntelliSense](https://github.com/fractalmandala/styles-intellisense)
+VS Code extension — class completions and hovers inside `class="…"`, token
+completions on `--custom-properties` — pointing at wherever your styles now
+live (`node_modules/…/dist/styles` in track mode, your local folder in eject
+mode), plus the copied `REGISTRY.api.md` as the description source. It also
+checks the extension is installed and prints how to get it if not.
+
+`npx @fractaldesign/fractalstyler init` with no flags asks the three questions
+interactively; `--yes` takes the defaults (track + docs + intellisense).
+
+## CLI reference
+
+```sh
+npx @fractaldesign/fractalstyler init     # scaffold: mode, docs, intellisense
+npx @fractaldesign/fractalstyler eject    # copy styles + palettes + builder
+npx @fractaldesign/fractalstyler lint     # contract linter (self or <dir>)
+npx @fractaldesign/fractalstyler help     # all options
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--track` / `--eject` | track | How the styles are held |
+| `--docs` / `--no-docs` | docs | Copy registry + configuration docs |
+| `--docs-dir <dir>` | `fractalstyler/` | Where docs land |
+| `--styles-dir <dir>` | `src/lib/styles` | Eject target for the layers |
+| `--palette-dir <dir>` | `src/lib/palette` | Eject target for the palettes |
+| `--scripts-dir <dir>` | `scripts` | Eject target for the registry builder |
+| `--intellisense` / `--no-intellisense` | ask | VS Code extension settings + check |
+| `--yes` / `-y` | — | Non-interactive, take the defaults |
+
+`lint` needs the Sass compiler (an optional peer of this package):
+`pnpm add -D sass`. Its own flags (`--json`, `--own <file>`, `--registry <f>`)
+pass through unchanged.
+
+## Developing this package
+
+```sh
+pnpm registry   # regenerate registry.json, REGISTRY.md, docs, skill references
+pnpm vocab      # regenerate docs/REGISTRY.api.md
+pnpm browser    # regenerate docs/browser.html
+pnpm lint       # contract linter (self mode)
+pnpm check      # validate-deck + svelte-check
+pnpm css        # rebuild dist/css
+```
+
+Architecture: **L0 (Tokens) → L1 (Dimensions) → L2 (Containers) → L3
+(Layouts) → L4 (Shells) → L5 (Visuals & Interactions)** — the layer map and
+the edit recipes are in [`docs/references/configurations.md`](docs/references/configurations.md).

package/cli/main.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// =============================================================================
+// fractalstyler — the consumer-facing CLI.
+//
+//   npx @fractaldesign/fractalstyler init     scaffold: track or eject, docs,
+//                                            intellisense (interactive, or flags)
+//   npx @fractaldesign/fractalstyler eject    copy the styles + palettes +
+//                                            registry builder into your project
+//   npx @fractaldesign/fractalstyler lint     contract linter (self or <dir>)
+//
+// Zero dependencies beyond Node itself.
+// ============================================================================
+
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runInit, runEject } from './scaffold.mjs';
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const USAGE = `fractalstyler — the composition styling system, as a CLI
+
+Usage:
+  fractalstyler init [options]     Scaffold a project (default command)
+  fractalstyler eject [options]    Copy the styles sources into your project
+  fractalstyler lint [dir] [flags]  Contract linter (self mode, or a target dir)
+  fractalstyler help               This message
+
+init options:
+  --track                 Track the package: styles stay in node_modules,
+                          upgrades come from npm (default)
+  --eject                 Eject: the style files become yours (see eject)
+  --docs / --no-docs      Copy the registry + configurations docs into the
+                          project (default: yes)
+  --docs-dir <dir>        Where docs land (default: fractalstyler/)
+  --intellisense / --no-intellisense
+                          Write .vscode settings for the Styles IntelliSense
+                          extension and check it is installed (default: ask;
+                          --yes takes yes)
+  --yes / -y              Non-interactive: take the defaults above
+
+eject options (same docs/intellisense flags, plus):
+  --styles-dir <dir>      Target for the style layers (default: src/lib/styles)
+  --palette-dir <dir>     Target for the palette modules (default: src/lib/palette)
+  --scripts-dir <dir>     Target for the registry builder (default: scripts)
+
+Never overwrites an existing file: on a name conflict the existing file is
+kept and yours is reported. Delete a kept file and re-run to re-place it.
+
+How the styles activate:
+  track:  pnpm add -D @fractaldesign/fractalstyler
+          @use '@fractaldesign/fractalstyler/styles' as *
+          (or plain CSS: import '@fractaldesign/fractalstyler/css')
+  eject:  the copy lands in src/lib/styles/ — import it from your own tree and
+          regenerate your registry after edits with node scripts/build-registry.mjs
+          (Node only, no Sass needed).`;
+
+function fail(message) {
+	console.error(`✕ ${message}\n`);
+	console.error('Run `fractalstyler help` for usage.');
+	process.exit(1);
+}
+
+const args = process.argv.slice(2);
+const command = args[0] && !args[0].startsWith('-') ? args[0] : 'init';
+const rest = args[0] && !args[0].startsWith('-') ? args.slice(1) : args;
+
+function parseOptions(rest) {
+	const opts = {
+		mode: null,
+		docs: null,
+		intellisense: null,
+		docsDir: 'fractalstyler',
+		stylesDir: 'src/lib/styles',
+		paletteDir: 'src/lib/palette',
+		scriptsDir: 'scripts',
+		yes: false
+	};
+	for (let i = 0; i < rest.length; i++) {
+		const arg = rest[i];
+		switch (arg) {
+			case '--track': opts.mode = 'track'; break;
+			case '--eject': opts.mode = 'eject'; break;
+			case '--docs': opts.docs = true; break;
+			case '--no-docs': opts.docs = false; break;
+			case '--intellisense': opts.intellisense = true; break;
+			case '--no-intellisense': opts.intellisense = false; break;
+			case '--yes': case '-y': opts.yes = true; break;
+			case '--docs-dir': case '--styles-dir': case '--palette-dir': case '--scripts-dir': {
+				const value = rest[++i];
+				if (!value) fail(`${arg} needs a value.`);
+				opts[arg.slice(2) + 'Dir'] = value.replace(/[/\\]+$/, '');
+				break;
+			}
+			default:
+				fail(`unknown option: ${arg}`);
+		}
+	}
+	return opts;
+}
+
+switch (command) {
+	case 'init': {
+		const opts = parseOptions(rest);
+		await runInit(opts, PKG_ROOT);
+		break;
+	}
+	case 'eject': {
+		const opts = parseOptions(rest);
+		opts.mode = 'eject';
+		await runEject(opts, PKG_ROOT);
+		break;
+	}
+	case 'lint': {
+		// Delegate to the contract linter verbatim — it already understands
+		// self mode (no args) and consumer mode (`lint <dir>`), plus its own
+		// flags (--json, --own, --registry). The linter compiles the stylesheet
+		// for exact matching, so it needs `sass` — an optional peer of this
+		// package. Check up front and say how to get it, instead of letting the
+		// consumer watch a module-resolution crash.
+		const require = createRequire(import.meta.url);
+		try {
+			require.resolve('sass', { paths: [process.cwd(), PKG_ROOT] });
+		} catch {
+			console.error('✕ lint needs the Sass compiler, which is not installed here.');
+			console.error('  It is an optional peer of this package — add it, then re-run:');
+			console.error('    pnpm add -D sass      (or: npm i -D sass)');
+			process.exit(1);
+		}
+		const lint = join(PKG_ROOT, 'lint', 'cli.mjs');
+		const result = spawnSync(process.execPath, [lint, ...rest], { stdio: 'inherit' });
+		process.exit(result.status ?? 1);
+		break;
+	}
+	case 'help': case '--help': case '-h':
+		console.log(USAGE);
+		break;
+	default:
+		fail(`unknown command: ${command}`);
+}