native-sfc 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YieldRay
+
+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

@@ -0,0 +1,46 @@
+# Native-SFC
+
+Load a single HTML file as a Web Component.
+
+## How it works
+
+The component loader fetches everything (HTML, JS, CSS) as text,
+then processes them to create a Web Component.
+
+1. **HTML Parsing**: The HTML file is parsed and processed
+2. **Style Handling**: All `<style>` and `<link rel="stylesheet">` are collected and converted to `adoptedStyleSheets` of the component's shadow root (avoids FOUC)
+3. **Script Handling**: ESM modules (`<script type="module">`) are evaluated and their exports are merged. The `default` export, if it's a class extending `HTMLElement`, becomes the base class of the component
+4. **Global Styles**: Styles with `global` attribute are moved to the outer document instead of the shadow root
+5. **URL Rewriting**: All relative URLs in `src` and `href` attributes are rewritten to absolute URLs based on the component file location
+
+## API
+
+### `loadComponent(name, url, afterConstructor?)`
+
+Load a component from a HTML file and register it as a custom element.
+
+- `name`: The custom element name (e.g., `"my-component"`)
+- `url`: The URL to the component HTML file (relative to the importer)
+- `afterConstructor`: Optional callback executed after the component constructor
+
+### `defineComponent(fc)`
+
+A helper function for dual-mode component definition:
+
+- When used inside a `loadComponent`-imported module, it defines a web component class
+- When used in normal document context, it runs the function with `document` as root
+
+## Limitations
+
+- Dynamic imports with relative paths are NOT supported.
+- Inside the ESM modules, the `from` syntax in import statements are rewritten to absolute URL, since all modules are actually loaded as blob URLs.
+- Since all styles are moved to `adoptedStyleSheets` in component's shadow root, we CANNOT use `@import` rules in styles.
+- Relative URLs in CSS (e.g., `background-image: url(./bg.png)`) are resolved relative to the main document (the page URL), not the component file URL.
+- Components loaded with the same name and URL are cached and reused.
+- Only `script[src]`'s src' `link[rel="stylesheet"]`'s href will be rewritten. Warn that `a[href]`/`img[src]`/etc with relative URLs in the HTML body will NOT be rewritten.
+
+## Next Steps
+
+- Implement component debugger
+- Implement component bundler in both runtime and server-side
+- Consider to support rewriting relative URLs in CSS