@shineuix/ssr 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShineUI contributors
+
+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,112 @@
-# Temporary Holding Version
+# @shineuix/ssr
 
-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.
+Server rendering for ShineUI. Install it only if you
+server-render. `@shineuix/core` is byte for byte the same whether or not you do.
+
+```sh
+npm i @shineuix/ssr
+```
+
+## Why it is a separate package
+
+Stencil compiles hydration into the client runtime for a whole build as soon as a hydrate output
+target exists in the config. Measured on the core build, adding one cost a fixed
+**2,665 bytes gzipped on every bundle**, +24% on a single button, paid by every consumer whether or
+not they ever server-render. Shipping the artefacts inside `@shineuix/core` instead cost the tarball
+**+33%**, 3.88 MB to 5.17 MB, for the same set of people.
+
+So server rendering is a second build of the same source, published here. The default build has
+no hydrate target, so it cannot compile hydration in.
+
+## Both halves
+
+```js
+// server
+import { renderToString } from '@shineuix/ssr';
+
+const { html } = await renderToString(
+  '<sui-button variant="accent" label="Pay bills"></sui-button>',
+  { prettyHtml: false }
+);
+```
+
+```js
+// client: the same elements, compiled with hydration. One call per element.
+import { defineCustomElement } from '@shineuix/ssr/components/sui-button.js';
+defineCustomElement();
+```
+
+To register every element at once, read the bulk module and call what it gives you:
+
+```js
+import * as hydrated from '@shineuix/ssr/components';
+for (const [name, define] of Object.entries(hydrated)) {
+  if (name.startsWith('defineCustomElement')) define();
+}
+```
+
+This package has no `defineCustomElements()`. That one belongs to `@shineuix/core/loader`, which is
+the non-hydrating path. The build here uses Stencil's `single-export-module` behavior, so each
+element ships its own `defineCustomElement` and a page pays only for what it registers.
+
+You need both halves. The client half is what lets the browser take the server markup over. Import
+the ordinary `@shineuix/core/components` on a server-rendered page and it will rebuild the DOM
+instead, which is the flash you were server-rendering to avoid.
+
+## Data that is not an attribute
+
+An array, an object or a function cannot be an attribute. Set those properties in `beforeHydrate`,
+which runs on the render's own document before the elements start, and the elements render with
+them:
+
+```js
+const { html } = await renderToString(page, {
+  async beforeHydrate(doc) {
+    const table = doc.querySelector('#invoices');
+    table.columns = columns;
+    table.rows = await loadInvoices(customerId);
+  },
+});
+```
+
+Set the same properties on the client before you register the elements. A render callback runs on
+the server too, where there is no global `document`: return a string, or build nodes with `doc`.
+
+## Language
+
+Each render takes its language in its options: `language` (or the document's own `<html lang>`)
+picks the tag, and `locales` hands that render its packs, the objects `registerLocale` takes in a
+browser. Renders running at the same time keep their own packs, because each runs in a window of
+its own; for the same reason `registerLocale` and `setLocale` in server code reach no render.
+
+```js
+import de from '@shineuix/core/locales/de';
+
+const { html } = await renderToString(body, { language: 'de', locales: { de } });
+```
+
+## Per framework
+
+- **Plain HTML and Vite** work as above.
+- **React**: `@shineuix/react`'s components render an empty tag on the server, so a React page
+  server-renders its own markup and the elements draw on the client, with no hydration mismatch.
+- **Vue**: `@shineuix/vue`'s components render nothing on the server, and the elements draw once the
+  page has mounted, with no hydration mismatch and no `<ClientOnly>`.
+- **Angular**: keep hydration on and give each of your components that holds ShineUI elements
+  `host: { ngSkipHydration: 'true' }`; the `@shineuix/angular` readme has the detail.
+
+## Optional libraries
+
+Three elements fetch a library only when their feature runs, and those stay out of the server
+bundle: Shiki for `sui-code-block` and `sui-terminal`, ProseMirror for `sui-rich-text-editor`, the QR
+encoder for `sui-qr-code`. Install them on the server only if you render those elements there.
+
+## Versioning
+
+This package and `@shineuix/core` are released together and the peer range is the exact version. Two
+copies of the elements built from different sources will hydrate markup they no longer match, and
+that failure is quiet, so install both at the same version.
+
+Documentation and live demos: [shineui.dev/server-rendering](https://shineui.dev/server-rendering).
+
+MIT. Copyright 2026 ShineUI contributors.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,256 @@
+# Third-party notices
+
+ShineUI is MIT licensed (see `LICENSE`). Its packages redistribute the third-party work listed
+here, under the terms below. This file ships in the `@shineuix/core` and `@shineuix/ssr` tarballs,
+because those two carry compiled copies of other people's code; the bindings install their
+dependencies from the registry with each package's own licence file beside it.
+
+## Code compiled into the packages
+
+The custom elements build inlines the libraries below into the chunks of `@shineuix/core`
+(`dist/components`, `dist/shineui`, `dist/esm`, `dist/cjs`) and of `@shineuix/ssr`
+(`dist/components`, `dist/hydrate`). The minifier strips their licence banners, so the copyright
+notices are reproduced here as the MIT licence requires. Every library in this section is MIT
+licensed; the licence text follows the list.
+
+- **Stencil runtime** (`@stencil/core`, the client runtime compiled into every chunk).
+  Copyright (c) 2019-present Drifty Co.
+- **ProseMirror**, the engine behind `sui-rich-text-editor` and `sui-edit-box`
+  (`prosemirror-commands`, `prosemirror-history`, `prosemirror-inputrules`, `prosemirror-keymap`,
+  `prosemirror-model`, `prosemirror-schema-basic`, `prosemirror-schema-list`, `prosemirror-state`,
+  `prosemirror-transform`, `prosemirror-view`, and their helpers `orderedmap`, `rope-sequence`,
+  `w3c-keyname`). Copyright (C) 2015-2017 by Marijn Haverbeke and others.
+- **Shiki**, the highlighter behind `sui-code-block` (`shiki`, `@shikijs/core`,
+  `@shikijs/engine-javascript`, `@shikijs/langs` for the eight grammars the element loads,
+  `@shikijs/types`). Copyright (c) 2021 Pine Wu. Copyright (c) 2023 Anthony Fu.
+  The grammars in `@shikijs/langs` are collected from their upstream TextMate bundles, whose
+  sources and licences are listed in that package's collection.
+- **vscode-textmate** (`@shikijs/vscode-textmate`, the grammar engine Shiki runs).
+  Copyright (c) Microsoft Corporation.
+- **oniguruma-to-es** and its parser and regex helpers (`oniguruma-to-es`, `oniguruma-parser`,
+  `regex`, `regex-recursion`, `regex-utilities`), the JavaScript regex engine Shiki uses here.
+  Copyright (c) 2024-2026 Steven Levithan.
+- **hast-util-to-html** and the unified helpers it brings (`hast-util-whitespace`,
+  `html-void-elements`, `property-information`, `stringify-entities`, `character-entities-html4`,
+  `character-entities-legacy`, `comma-separated-tokens`, `space-separated-tokens`, `ccount`,
+  `zwitch`, `mdast-util-to-hast`, `micromark-util-character`, `micromark-util-encode`,
+  `micromark-util-sanitize-uri`, `micromark-util-symbol`, `trim-lines`, `unist-util-is`,
+  `unist-util-position`, `unist-util-visit`, `unist-util-visit-parents`, `vfile`, `vfile-message`,
+  `unist-util-stringify-position`, `devlop`), the serializer Shiki writes its output with; the
+  bundler keeps the parts the highlighter reaches. Copyright (c) Titus Wormer. `dequal`:
+  Copyright (c) Luke Edwards.
+- **node-qrcode** (`qrcode`), behind `sui-qr-code`. Copyright (c) 2012 Ryan Day. Its encoder is
+  based on QRCode for JavaScript, Copyright (c) 2009 Kazuhiko Arase (MIT). Its path finder
+  `dijkstrajs`: Copyright (C) 2008 Wyatt Baldwin, adapted from the Dijkstar project.
+
+The MIT licence, which applies to each of the above:
+
+```
+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.
+```
+
+## Code the server build compiles into @shineuix/ssr
+
+<!-- generated by scripts/third-party.mjs: server build begin -->
+
+`@shineuix/ssr` carries Stencil's server runtime in `dist/hydrate`: its mock document and hydrate runner (Stencil, MIT, listed above), and the libraries those inline, below, as found in @stencil/core 4.44.2. Each line is the library, what it does there, its licence and its copyright notice; the licence texts other than MIT's follow.
+
+- **balanced-match**: brace-expansion's bracket matcher. MIT; Copyright (c) 2013 Julian Gruber <julian@juliangruber.com>
+- **brace-expansion**: minimatch's brace expansion. MIT; Copyright (c) 2013 Julian Gruber <julian@juliangruber.com>
+- **entities**: parse5's character reference decoder and the runner's escaper. BSD-2-Clause; Copyright (c) Felix Böhm. All rights reserved.
+- **jquery** 4.0.0-pre+9352011a7.dirty: the selector engine behind the mock document's querySelector. MIT; Copyright OpenJS Foundation and other contributors
+- **minimatch** 9.0.9: the hydrate runner's glob matcher. ISC; Copyright (c) 2011-2023 Isaac Z. Schlueter and Contributors
+- **parse5** 7.2.1: the HTML parser of the mock document and the hydrate runner. MIT; Copyright (c) 2013-2019 Ivan Nikulin (ifaaan@gmail.com, https://github.com/inikulin)
+- **shadow-css**: Stencil's port of the Angular shadow CSS scoper (`src/utils/shadow-css.ts`), from webcomponents.js. MIT; Copyright Google Inc. All Rights Reserved.
+
+The BSD-2-Clause licence, which applies to entities:
+
+```
+Redistribution and use in source and binary forms, with or without modification, are permitted
+provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and
+the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions
+and the following disclaimer in the documentation and/or other materials provided with the
+distribution.
+
+THIS IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+THE USE OF THIS, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+
+The ISC licence, which applies to minimatch:
+
+```
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without
+fee is hereby granted, provided that the above copyright notice and this permission notice appear
+in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
+SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
+AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+```
+
+<!-- generated by scripts/third-party.mjs: server build end -->
+
+## Fonts and icons
+
+- **DM Sans** ships inside `@shineuix/core` as `dist/shineui/fonts/dmsans-latin.woff2` under the
+  SIL Open Font License 1.1; the licence travels with the font as `dist/shineui/fonts/OFL.txt`.
+  Only the optional `@shineuix/core/shineui-fonts.css` loads it. The copy is modified as the licence
+  allows: the Latin subset with tabular figures added by `scripts/font/add-tnum.py`, and nothing
+  else changed.
+- **Font Awesome 6 Free**, the icon font, is neither bundled nor loaded by any ShineUI package or
+  stylesheet. A page that uses Font Awesome classes loads it itself, under Font Awesome's terms:
+  CC BY 4.0 for the icons, SIL OFL 1.1 for the font files, MIT for the code.
+
+## Packages installed beside the ShineUI packages, and the trees compiled in
+
+The production dependency tree of the five packages, as `node scripts/third-party.mjs` walks it
+from the installed workspace, and the tree of every library `@shineuix/core` compiles into its own
+files (the libraries in the first section above, with what they bring), so each licence among them
+is listed. `@shineuix/core` installs nothing else. The bindings' runtime dependencies (`@lit/react`, `tslib` and their
+trees) are installed by the package manager from the registry, each with its own licence file, and
+are not compiled into ShineUI's files. `@shineuix/react` carries one file copied from
+`@stencil/react-output-target` (`src/runtime.ts`, MIT, Copyright (c) 2019-present Drifty Co.), and
+`@shineuix/vue` one from `@stencil/vue-output-target` (`src/runtime.ts`, MIT, Copyright (c)
+2019-present Drifty Co.), each with the notice at the top of the file. `@shineuix/core` draws the elements' own glyphs from the path
+data of Font Awesome Free (`packages/core/src/components/_shared/glyphs.ts`, generated from
+`@fortawesome/fontawesome-free`; icons CC BY 4.0, Copyright Fonticons, Inc.,
+https://fontawesome.com/license/free), with the attribution at the top of that file; the icon font
+itself is not shipped, and a page that wants Font Awesome classes for its own icons loads Font
+Awesome itself.
+
+<!-- generated by scripts/third-party.mjs: begin -->
+
+89 packages, resolved from the installed workspace by walking each package's dependencies, and the libraries @shineuix/core compiles into its files with their own dependencies (optional platform binaries are build tools and are left out). Each line is the package, its licence, and the package that pulls it in.
+
+### Installed with @shineuix/react
+
+- @lit/react: BSD-3-Clause
+
+### Installed with @shineuix/angular
+
+- tslib: 0BSD
+
+### Compiled into @shineuix/core
+
+- @shikijs/core: MIT (through shiki)
+- @shikijs/engine-javascript: MIT (through shiki)
+- @shikijs/engine-oniguruma: MIT (through shiki)
+- @shikijs/langs: MIT (through shiki)
+- @shikijs/themes: MIT (through shiki)
+- @shikijs/types: MIT (through @shikijs/core)
+- @shikijs/vscode-textmate: MIT (through shiki)
+- @stencil/core: MIT
+- @types/hast: MIT (through shiki)
+- @types/mdast: MIT (through mdast-util-to-hast)
+- @types/unist: MIT (through @types/hast)
+- @ungap/structured-clone: ISC (through mdast-util-to-hast)
+- ansi-regex: MIT (through strip-ansi)
+- ansi-styles: MIT (through wrap-ansi)
+- camelcase: MIT (through yargs-parser)
+- ccount: MIT (through hast-util-to-html)
+- character-entities-html4: MIT (through stringify-entities)
+- character-entities-legacy: MIT (through stringify-entities)
+- cliui: ISC (through yargs)
+- color-convert: MIT (through ansi-styles)
+- color-name: MIT (through color-convert)
+- comma-separated-tokens: MIT (through hast-util-to-html)
+- decamelize: MIT (through yargs)
+- dequal: MIT (through devlop)
+- devlop: MIT (through mdast-util-to-hast)
+- dijkstrajs: MIT (through qrcode)
+- emoji-regex: MIT (through string-width)
+- find-up: MIT (through yargs)
+- get-caller-file: ISC (through yargs)
+- hast-util-to-html: MIT (through @shikijs/core)
+- hast-util-whitespace: MIT (through hast-util-to-html)
+- html-void-elements: MIT (through hast-util-to-html)
+- is-fullwidth-code-point: MIT (through string-width)
+- locate-path: MIT (through find-up)
+- mdast-util-to-hast: MIT (through hast-util-to-html)
+- micromark-util-character: MIT (through micromark-util-sanitize-uri)
+- micromark-util-encode: MIT (through micromark-util-sanitize-uri)
+- micromark-util-sanitize-uri: MIT (through mdast-util-to-hast)
+- micromark-util-symbol: MIT (through micromark-util-character)
+- micromark-util-types: MIT (through micromark-util-character)
+- oniguruma-parser: MIT (through oniguruma-to-es)
+- oniguruma-to-es: MIT (through @shikijs/engine-javascript)
+- orderedmap: MIT (through prosemirror-model)
+- p-limit: MIT (through p-locate)
+- p-locate: MIT (through locate-path)
+- p-try: MIT (through p-limit)
+- path-exists: MIT (through find-up)
+- pngjs: MIT (through qrcode)
+- property-information: MIT (through hast-util-to-html)
+- prosemirror-commands: MIT
+- prosemirror-history: MIT
+- prosemirror-inputrules: MIT
+- prosemirror-keymap: MIT
+- prosemirror-model: MIT (through prosemirror-commands)
+- prosemirror-schema-basic: MIT
+- prosemirror-schema-list: MIT
+- prosemirror-state: MIT (through prosemirror-commands)
+- prosemirror-transform: MIT (through prosemirror-commands)
+- prosemirror-view: MIT (through prosemirror-state)
+- qrcode: MIT
+- regex: MIT (through oniguruma-to-es)
+- regex-recursion: MIT (through oniguruma-to-es)
+- regex-utilities: MIT (through regex)
+- require-directory: MIT (through yargs)
+- require-main-filename: ISC (through yargs)
+- rope-sequence: MIT (through prosemirror-history)
+- set-blocking: ISC (through yargs)
+- shiki: MIT
+- space-separated-tokens: MIT (through hast-util-to-html)
+- string-width: MIT (through cliui)
+- stringify-entities: MIT (through hast-util-to-html)
+- strip-ansi: MIT (through string-width)
+- trim-lines: MIT (through mdast-util-to-hast)
+- unist-util-is: MIT (through unist-util-visit)
+- unist-util-position: MIT (through mdast-util-to-hast)
+- unist-util-stringify-position: MIT (through vfile-message)
+- unist-util-visit: MIT (through mdast-util-to-hast)
+- unist-util-visit-parents: MIT (through unist-util-visit)
+- vfile: MIT (through mdast-util-to-hast)
+- vfile-message: MIT (through vfile)
+- w3c-keyname: MIT (through prosemirror-keymap)
+- which-module: ISC (through yargs)
+- wrap-ansi: MIT (through cliui)
+- y18n: ISC (through yargs)
+- yargs: MIT (through qrcode)
+- yargs-parser: ISC (through yargs)
+- zwitch: MIT (through hast-util-to-html)
+
+### By licence
+
+- MIT: 79
+- ISC: 8
+- BSD-3-Clause: 1
+- 0BSD: 1
+
+<!-- generated by scripts/third-party.mjs: end -->