@ifloppy/maxcraftmc-ui-svelte 0.1.0

package/css/white.scss

@@ -0,0 +1,33 @@
+// Use the "white" (White) Carbon theme
+@import "carbon-components/scss/globals/scss/vendor/@carbon/themes/scss";
+
+$carbon--theme: $carbon--theme--white;
+@include carbon--theme();
+
+$feature-flags: (
+  ui-shell: true,
+  grid-columns-16: true
+);
+
+$css--font-face: true;
+$css--helpers: true;
+$css--body: true;
+$css--use-layer: true;
+$css--reset: true;
+$css--default-type: true;
+$css--plex: true;
+
+@import "carbon-components/scss/globals/scss/component-tokens";
+@import "carbon-components/src/components/tag/tag";
+@import "carbon-components/src/components/notification/inline-notification";
+@import "carbon-components/src/components/notification/toast-notification";
+@import "./popover";
+
+@import "carbon-components/scss/globals/scss/_css--reset";
+@import "carbon-components/scss/globals/scss/_css--font-face";
+@import "carbon-components/scss/globals/scss/_css--helpers";
+@import "carbon-components/scss/globals/scss/_css--body";
+@import "carbon-components/scss/globals/grid/grid";
+
+// Import all component styles
+@import "carbon-components/scss/globals/scss/styles";

package/docs/compatibility.md

@@ -0,0 +1,53 @@
+# Compatibility Policy
+
+The compatibility target is fixed to `carbon-components-svelte@0.89.4`.
+
+## Guaranteed Surface
+
+This package preserves:
+
+- `src/index.js` named exports
+- `types/index.d.ts` named exports
+- component directory names
+- component file names
+- CSS entrypoints under `css/`
+- common props, events, slots, and rest-prop behavior inherited from Carbon
+  Svelte 0.89.4
+
+The API check script compares the package exports against the type export list:
+
+```sh
+npm run check
+```
+
+The same command also builds a temporary Svelte/Vite app that imports
+representative components and CSS from this package. This catches missing
+runtime dependencies and broken Svelte entrypoints that text-only export checks
+cannot see.
+
+## Non-Goals
+
+- This package does not track newer Carbon packages such as `@carbon/*`.
+- This package does not replace `carbon-icons-svelte`.
+- This package does not guarantee visual parity with IBM Carbon; MaxCraft visual
+  language is the intended output.
+
+## Adding Or Changing Components
+
+Before changing a component API:
+
+1. Compare against `carbon-components-svelte@0.89.4`.
+2. Preserve existing prop/event/slot names unless a breaking release is planned.
+3. Run `npm run check`.
+4. Verify `mpc-web` with `npm run check` and `npm run build`.
+
+If a component needs MaxCraft-specific behavior, prefer CSS/token customization
+first. Add new props only when CSS cannot express the requirement.
+
+## Versioning
+
+Use semantic versioning:
+
+- Patch: style fixes, docs, compatibility bug fixes
+- Minor: new MaxCraft styling hooks or non-breaking helper exports
+- Major: breaking API changes against Carbon Svelte 0.89.4

package/docs/component-catalog.md

@@ -0,0 +1,99 @@
+# Component Catalog
+
+This catalog mirrors the public exports in `src/index.js`. The compatibility
+target is `carbon-components-svelte@0.89.4`.
+
+## Inputs And Forms
+
+- `Button`, `ButtonSkeleton`, `ButtonSet`
+- `Checkbox`, `CheckboxSkeleton`
+- `ComboBox`
+- `Dropdown`, `DropdownSkeleton`
+- `Form`, `FluidForm`, `FormGroup`, `FormItem`, `FormLabel`
+- `MultiSelect`
+- `NumberInput`, `NumberInputSkeleton`
+- `RadioButton`, `RadioButtonSkeleton`, `RadioButtonGroup`
+- `Search`, `SearchSkeleton`
+- `Select`, `SelectSkeleton`, `SelectItem`, `SelectItemGroup`
+- `Slider`, `SliderSkeleton`
+- `TextArea`, `TextAreaSkeleton`
+- `TextInput`, `TextInputSkeleton`, `PasswordInput`
+- `TimePicker`, `TimePickerSelect`
+- `Toggle`, `ToggleSkeleton`
+
+## Layout And Navigation
+
+- `Accordion`, `AccordionItem`, `AccordionSkeleton`
+- `AspectRatio`
+- `Breadcrumb`, `BreadcrumbItem`, `BreadcrumbSkeleton`
+- `ContentSwitcher`, `Switch`
+- `Grid`, `Row`, `Column`
+- `Header`, `HeaderAction`, `HeaderActionLink`, `HeaderNav`, `HeaderNavItem`, `HeaderNavMenu`
+- `HeaderPanelDivider`, `HeaderPanelLink`, `HeaderPanelLinks`
+- `HeaderUtilities`, `HeaderGlobalAction`, `HeaderSearch`
+- `SideNav`, `SideNavItems`, `SideNavLink`, `SideNavMenu`, `SideNavMenuItem`, `SideNavDivider`
+- `Content`, `SkipToContent`
+- `Tabs`, `Tab`, `TabContent`, `TabsSkeleton`
+- `TreeView`
+
+## Data Display
+
+- `CodeSnippet`, `CodeSnippetSkeleton`
+- `DataTable`, `DataTableSkeleton`
+- `Table`, `TableBody`, `TableCell`, `TableContainer`, `TableHead`, `TableHeader`, `TableRow`
+- `Toolbar`, `ToolbarContent`, `ToolbarSearch`, `ToolbarBatchActions`, `ToolbarMenu`, `ToolbarMenuItem`
+- `Link`, `OutboundLink`
+- `ListBox`, `ListBoxField`, `ListBoxMenu`, `ListBoxMenuIcon`, `ListBoxMenuItem`, `ListBoxSelection`
+- `ListItem`
+- `OrderedList`, `UnorderedList`
+- `Pagination`, `PaginationSkeleton`, `PaginationNav`
+- `StructuredList`, `StructuredListSkeleton`, `StructuredListBody`, `StructuredListHead`
+- `StructuredListCell`, `StructuredListRow`, `StructuredListInput`
+- `Tag`, `TagSkeleton`
+- `Tile`, `ClickableTile`, `ExpandableTile`, `SelectableTile`, `RadioTile`, `TileGroup`
+- `Truncate`
+
+## Feedback And Overlays
+
+- `ComposedModal`, `ModalHeader`, `ModalBody`, `ModalFooter`
+- `Modal`
+- `InlineLoading`
+- `Loading`
+- `InlineNotification`, `ToastNotification`
+- `NotificationActionButton`, `NotificationButton`, `NotificationIcon`
+- `Popover`
+- `ProgressBar`
+- `ProgressIndicator`, `ProgressIndicatorSkeleton`, `ProgressStep`
+- `Tooltip`, `TooltipFooter`
+- `TooltipDefinition`
+- `TooltipIcon`
+
+## Utilities And Helpers
+
+- `Breakpoint`
+- `breakpointObserver`
+- `breakpoints`
+- `ContextMenu`, `ContextMenuDivider`, `ContextMenuGroup`, `ContextMenuOption`, `ContextMenuRadioGroup`
+- `CopyButton`
+- `DatePicker`, `DatePickerInput`, `DatePickerSkeleton`
+- `FileUploader`, `FileUploaderButton`, `FileUploaderItem`, `FileUploaderDropContainer`
+- `Filename`, `FileUploaderSkeleton`
+- `ImageLoader`
+- `LocalStorage`
+- `RecursiveList`
+- `SkeletonPlaceholder`
+- `SkeletonText`
+- `Theme`
+- `truncate`
+- `toHierarchy`
+
+## Styling Status
+
+All components keep the Carbon Svelte 0.89.4 API surface. MaxCraft visual
+styling is currently applied through `css/maxcraft.css` as a shared override
+layer. Components not explicitly targeted by the override layer still inherit
+Carbon-compatible layout and MaxCraft token colors where they use Carbon custom
+properties.
+
+For new MaxCraft-specific visual work, prefer adding token-backed CSS overrides
+instead of changing component props.

package/docs/consumer-checklist.md

@@ -0,0 +1,42 @@
+# Consumer Migration Checklist
+
+Use this checklist when connecting a Svelte or Hugo consumer to
+`@ifloppy/maxcraftmc-ui-svelte`.
+
+## Svelte Consumer
+
+- Replace `carbon-components-svelte` with a local file alias during development:
+  `file:../maxcraft-ui`.
+- Replace the local alias with `npm:@ifloppy/maxcraftmc-ui-svelte@<version>` after
+  publishing.
+- Keep `carbon-icons-svelte` installed.
+- Remove `carbon-components` unless the app imports it directly.
+- Import `carbon-components-svelte/css/all.css` once in the root layout.
+- Import `carbon-components-svelte/css/maxcraft.css` once after `all.css`.
+- Keep existing component imports unchanged when using the alias.
+- Run `npm install --ignore-scripts`.
+- During local file-link development, also run `npm install --ignore-scripts`
+  inside `maxcraft-ui`.
+- Run `npm run check`.
+- Run `npm run build`.
+- Manually verify navigation, form controls, modals, notifications, tiles, tags,
+  and dark mode.
+
+## Hugo Consumer
+
+- Import `github.com/FloppyBetaStudio/maxcraft-ui` as a Hugo module and mount
+  its `css` directory to `assets/maxcraft-ui`.
+- If adding project-level mounts, explicitly restore default mounts for
+  `assets`, `content`, `layouts`, `static`, and any other site folders in use.
+- Include `maxcraft-ui/maxcraft.css` before site-specific CSS.
+- Keep page-specific layout and animation CSS in the consumer site.
+- Prefer shared `--mc-*` tokens for new theme styles.
+- Run `hugo --gc --minify`.
+- Confirm generated HTML links a fingerprinted `maxcraft` stylesheet.
+
+## Release Consumer
+
+- Update the consumer lockfile after changing from `file:` to `npm:`.
+- Run consumer checks after every package version bump.
+- Check for accidental duplicate CSS imports.
+- Keep `carbon-icons-svelte` version compatible with the consuming app.

package/docs/contributing.md

@@ -0,0 +1,80 @@
+# Contributing
+
+This package is both a compatibility layer and a MaxCraft design system. Treat
+compatibility as the default constraint.
+
+## Development Setup
+
+```sh
+npm install --ignore-scripts
+npm run check
+```
+
+When developing against `mpc-web`:
+
+```sh
+cd ../mpc-web
+npm install --ignore-scripts
+npm run check
+```
+
+## What To Change First
+
+- For visual work, prefer `tokens/maxcraft.css` and `css/maxcraft.css`.
+- For API fixes, compare against `carbon-components-svelte@0.89.4`.
+- For docs, update README links and run `npm run check`.
+- For consumer integration, update the relevant consumer docs and checklist.
+
+## Compatibility Rules
+
+- Do not rename exported components.
+- Do not remove props, events, slots, or CSS entrypoints that exist in Carbon
+  Svelte 0.89.4.
+- Do not replace `carbon-icons-svelte`.
+- Do not introduce framework support beyond Svelte unless the package scope is
+  explicitly changed.
+- Keep Hugo CSS reusable without requiring Svelte.
+
+## CSS Rules
+
+- Keep `css/maxcraft.css` self-contained.
+- Keep `tokens/maxcraft.css` focused on reusable design tokens.
+- Prefer `--mc-*` tokens over hard-coded colors.
+- Prefer CSS overrides over component API changes.
+- Preserve square, block-like UI affordances for shared controls.
+
+## Verification
+
+Run from `maxcraft-ui`:
+
+```sh
+npm run check
+npm run build
+```
+
+The local checks cover:
+
+- exact export parity with `carbon-components-svelte@0.89.4`
+- export target existence
+- a Vite/Svelte smoke build with representative components
+- placeholder/stub marker scanning
+- CSS entrypoint existence
+- documentation and README link integrity
+
+Run consumers when shared CSS or package metadata changes:
+
+```sh
+cd ../mpc-web
+npm run check
+npm run build
+
+cd ../maxcraftmc-wiki
+hugo --gc --minify
+```
+
+## GitNexus
+
+When editing existing symbols, run impact analysis before changes and
+`gitnexus detect-changes` before committing. Documentation-only changes usually
+do not map to symbols, but still run detect-changes before commit when the root
+repository requires it.

package/docs/hugo-integration.md

@@ -0,0 +1,94 @@
+# Hugo Integration Guide
+
+Hugo sites do not use Svelte components from this package. They reuse the CSS
+theme layer and design tokens.
+
+## 1. Mount The CSS Directory
+
+Initialize the Hugo site as a module if it does not already have `go.mod`:
+
+```sh
+hugo mod init github.com/YourOrg/your-site
+```
+
+Then import the public MaxCraft UI module and mount its CSS directory:
+
+```toml
+[[module.imports]]
+path = "github.com/FloppyBetaStudio/maxcraft-ui"
+
+[[module.imports.mounts]]
+source = "css"
+target = "assets/maxcraft-ui"
+```
+
+If the site declares any `module.mounts`, Hugo replaces the default mounts. Add
+all required site mounts explicitly:
+
+```toml
+[[module.mounts]]
+source = "assets"
+target = "assets"
+
+[[module.mounts]]
+source = "content"
+target = "content"
+
+[[module.mounts]]
+source = "layouts"
+target = "layouts"
+
+[[module.mounts]]
+source = "static"
+target = "static"
+```
+
+Add other project mounts such as `archetypes`, `data`, and `i18n` if the site
+uses them.
+
+## 2. Include The Stylesheet
+
+Include `maxcraft.css` before site-specific overrides:
+
+```go-html-template
+{{ with resources.Get "maxcraft-ui/maxcraft.css" }}
+{{ if hugo.IsProduction }}
+{{ $maxcraftUIStyles := . | minify | fingerprint }}
+<link rel="stylesheet" href="{{ $maxcraftUIStyles.RelPermalink }}" integrity="{{ $maxcraftUIStyles.Data.Integrity }}" />
+{{ else }}
+<link rel="stylesheet" href="{{ .RelPermalink }}" />
+{{ end }}
+{{ end }}
+```
+
+For `maxcraftmc-wiki`, the intended order is:
+
+1. Tailbliss/Tailwind base CSS
+2. `maxcraft-ui/maxcraft.css`
+3. Wiki-specific `css/site.css`
+
+This order gives the wiki the shared tokens while preserving its custom page
+layouts and animations.
+
+## 3. Use Shared Tokens
+
+Hugo templates and CSS can use the shared variables directly:
+
+```css
+.mc-button-primary {
+  background: linear-gradient(#5caf39, var(--mc-grass-dark));
+  border-color: var(--mc-border);
+}
+```
+
+Prefer token names over hard-coded colors for new shared UI styling.
+
+## 4. Build
+
+```sh
+hugo mod tidy
+hugo --gc --minify
+```
+
+Confirm the generated HTML contains a `maxcraft` stylesheet and the output
+folder contains a fingerprinted file under `public/maxcraft-ui/`.

package/docs/installation.md

@@ -0,0 +1,89 @@
+# Installation
+
+This package supports two consumption modes:
+
+- Svelte apps use the Carbon-compatible component entrypoint.
+- Hugo/static sites use the CSS/token entrypoints.
+
+## Published Package
+
+Install the package and keep `carbon-icons-svelte` as the icon source:
+
+```sh
+npm install @ifloppy/maxcraftmc-ui-svelte carbon-icons-svelte
+```
+
+For a new Svelte app, import directly:
+
+```js
+import { Button } from "@ifloppy/maxcraftmc-ui-svelte";
+import "@ifloppy/maxcraftmc-ui-svelte/css/all.css";
+import "@ifloppy/maxcraftmc-ui-svelte/css/maxcraft.css";
+```
+
+For an existing Carbon Svelte app, use an alias so source imports can stay
+unchanged:
+
+```json
+{
+  "dependencies": {
+    "carbon-components-svelte": "npm:@ifloppy/maxcraftmc-ui-svelte@0.1.0",
+    "carbon-icons-svelte": "^13.5.0"
+  }
+}
+```
+
+Existing imports continue to work:
+
+```js
+import { Button, Theme } from "carbon-components-svelte";
+import "carbon-components-svelte/css/all.css";
+import "carbon-components-svelte/css/maxcraft.css";
+```
+
+## Local Development In mpc-solution
+
+Use the local file alias while editing the UI package beside consumers:
+
+```json
+{
+  "dependencies": {
+    "carbon-components-svelte": "file:../maxcraft-ui",
+    "carbon-icons-svelte": "^13.5.0"
+  }
+}
+```
+
+Then install in both projects:
+
+```sh
+cd maxcraft-ui
+npm install --ignore-scripts
+
+cd ../mpc-web
+npm install --ignore-scripts
+```
+
+The `maxcraft-ui` install is needed during local file-link development because
+Vite resolves package source files through the real path and dependencies such
+as `flatpickr` must exist beside that source tree. Published npm installs do not
+need this extra step.
+
+## Required CSS Entrypoints
+
+The package preserves Carbon's original CSS entrypoints:
+
+- `css/all.css`
+- `css/white.css`
+- `css/g10.css`
+- `css/g80.css`
+- `css/g90.css`
+- `css/g100.css`
+
+MaxCraft-specific entrypoints:
+
+- `css/maxcraft.css`
+- `tokens/maxcraft.css`
+
+Use `all.css` plus `maxcraft.css` for Svelte apps. Use only `maxcraft.css` for
+Hugo/static sites that already have their own reset and prose styles.

package/docs/publishing.md

@@ -0,0 +1,74 @@
+# Publishing And Maintenance
+
+## Repository
+
+The intended public repository is:
+
+```sh
+github1:FloppyBetaStudio/maxcraft-ui.git
+```
+
+The root `mpc-solution` repository tracks this directory as a Git submodule.
+
+## Pre-Publish Checks
+
+Run from `maxcraft-ui`:
+
+```sh
+npm install --ignore-scripts
+npm run check
+npm run build
+```
+
+`npm run build` performs a dry-run package build with `npm pack --dry-run`.
+The check step verifies API parity, export targets, a Vite/Svelte smoke build,
+placeholder markers, CSS entrypoints, and documentation links.
+
+Also verify consumers:
+
+```sh
+cd ../mpc-web
+npm install --ignore-scripts
+npm run check
+npm run build
+
+cd ../maxcraftmc-wiki
+hugo --gc --minify
+```
+
+## Publish
+
+After the package is ready:
+
+```sh
+npm publish --access public
+```
+
+Then update consumers from local file aliases to npm aliases:
+
+```json
+{
+  "dependencies": {
+    "carbon-components-svelte": "npm:@ifloppy/maxcraftmc-ui-svelte@0.1.0"
+  }
+}
+```
+
+## Attribution Requirements
+
+Keep these files in every published package:
+
+- `LICENSE`
+- `NOTICE`
+- `README.md`
+
+Do not remove Carbon Svelte attribution. The source and type surface are derived
+from `carbon-components-svelte@0.89.4`, which is Apache-2.0 licensed.
+
+## Maintenance Checklist
+
+- Keep `css/maxcraft.css` self-contained for Hugo.
+- Keep `tokens/maxcraft.css` as the token source for future tooling.
+- Run API and CSS entrypoint checks before every release.
+- Test `mpc-web` and `maxcraftmc-wiki` before bumping the package version.
+- Avoid introducing a dependency on Carbon icons beyond `carbon-icons-svelte`.

package/docs/svelte-migration.md

@@ -0,0 +1,123 @@
+# Svelte Migration Guide
+
+This guide is for apps already using `carbon-components-svelte@0.89.4`, such as
+`mpc-web`.
+
+## 1. Replace The Dependency
+
+Local development:
+
+```json
+{
+  "dependencies": {
+    "carbon-components-svelte": "file:../maxcraft-ui",
+    "carbon-icons-svelte": "^13.5.0"
+  }
+}
+```
+
+Published package:
+
+```json
+{
+  "dependencies": {
+    "carbon-components-svelte": "npm:@ifloppy/maxcraftmc-ui-svelte@0.1.0",
+    "carbon-icons-svelte": "^13.5.0"
+  }
+}
+```
+
+Remove the old `carbon-components` dependency unless the app imports it
+directly. `@ifloppy/maxcraftmc-ui-svelte` includes the CSS entrypoints it needs.
+
+## 2. Keep Component Imports
+
+No source import rewrite is required when using the alias:
+
+```svelte
+<script>
+  import { Button, Header, Theme } from "carbon-components-svelte";
+</script>
+```
+
+Direct imports are also supported for new code:
+
+```svelte
+<script>
+  import { Button, Header, Theme } from "@ifloppy/maxcraftmc-ui-svelte";
+</script>
+```
+
+## 3. Load CSS Once
+
+Load CSS from the app root layout, not inside individual pages:
+
+```svelte
+<script>
+  import "carbon-components-svelte/css/all.css";
+  import "carbon-components-svelte/css/maxcraft.css";
+</script>
+```
+
+`all.css` keeps Carbon-compatible structure and base styles. `maxcraft.css`
+maps Carbon variables and common `bx--*` classes to MaxCraft visual language.
+
+## 4. Theme Mapping
+
+The `Theme` component still accepts Carbon theme names:
+
+```svelte
+<Theme theme={isDarkMode ? "g100" : "white"}>
+  <slot />
+</Theme>
+```
+
+MaxCraft maps them as:
+
+- `white`, `g10`: light
+- `g80`, `g90`, `g100`: dark
+
+## 5. Icons
+
+Continue using `carbon-icons-svelte`:
+
+```svelte
+<script>
+  import Home from "carbon-icons-svelte/lib/Home.svelte";
+  import { UserAvatarFilledAlt } from "carbon-icons-svelte";
+</script>
+```
+
+This UI package does not replace the Carbon icon package.
+
+## 6. Verification Checklist
+
+Run:
+
+```sh
+npm run check
+npm run build
+```
+
+Manually inspect:
+
+- Header and navigation
+- Buttons and button sets
+- Text inputs and forms
+- Dropdowns and modals
+- Toast/inline notifications
+- Tiles and tags
+- Light/dark theme switching
+- Mobile layout
+
+## Known Local Development Detail
+
+When using `file:../maxcraft-ui`, install dependencies in `maxcraft-ui` itself:
+
+```sh
+cd ../maxcraft-ui
+npm install --ignore-scripts
+```
+
+This avoids Vite resolution failures for transitive dependencies such as
+`flatpickr`.