@expressivecss/expressive 0.1.0-alpha.3 → 0.2.0

package/LICENSE

@@ -1,6 +1,7 @@
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2026 Javier Baez
+Copyright (c) 2026 BaezFJ
+Copyright (c) 2014-2026 Materialize
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +20,82 @@ 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.
+
+
+================================================================================
+THIRD-PARTY NOTICES
+================================================================================
+
+ExpressiveCSS is derived from MaterializeCSS v2.2.2
+(https://github.com/materializecss/materialize), which is distributed under the
+MIT license reproduced above. Portions of `src/ts` and `src/sass` remain
+substantially that work.
+
+The following components carry their own licenses, reproduced in full below.
+
+--------------------------------------------------------------------------------
+normalize.css v8.0.1 - MIT License
+https://github.com/necolas/normalize.css
+
+Used in: src/sass/base/_normalize.scss (trimmed to this project's browser
+support baseline; see that file's header for the list of removed rules).
+
+Copyright © Nicolas Gallagher and Jonathan Neal
+
+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.
+
+--------------------------------------------------------------------------------
+The Polymer Project - BSD 3-Clause License
+https://polymer.github.io/LICENSE.txt
+
+Used in: src/sass/components/_preloader.scss (spinner animation).
+
+The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
+The complete set of contributors may be found at
+http://polymer.github.io/CONTRIBUTORS.txt
+Code distributed by Google as part of the polymer project is also subject to an
+additional IP rights grant found at http://polymer.github.io/PATENTS.txt
+
+Copyright (c) 2014 The Polymer Authors. All rights reserved.
+
+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.
+   * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE 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
+OWNER 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 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,82 +1,192 @@
 # ExpressiveCSS
 
-A CSS framework inspired by Google's [Material Design 3 Expressive](https://material.io/) design language. Built on top of [MaterializeCSS v2.2.2](https://materializecss.github.io/materialize/), ExpressiveCSS aims to bring the expressive, dynamic, and personality-rich aesthetics of M3 Expressive to the web.
+ExpressiveCSS is a Material Design 3 front-end framework built with Sass and
+TypeScript. It provides theme tokens, layout and utility classes, styled form
+controls, and JavaScript components in browser, ES module, and CommonJS builds.
 
-> **Status: Early Alpha** — Actively under development. APIs and class names may change. Not yet recommended for production use.
+> ExpressiveCSS is currently at version `0.2.0` and under active development.
 
-## Vision
+## Features
 
-Google's M3 Expressive introduces a more vibrant, playful, and emotionally resonant layer to Material Design — prioritizing personality, motion, and visual richness. ExpressiveCSS brings that vision to a CSS framework you can drop into any project.
+- Material Design 3 color and typography tokens
+- Light and dark themes using CSS custom properties
+- Responsive grid and utility classes
+- Buttons, cards, forms, navigation, and other styled components
+- Interactive components including carousels, collapsibles, date pickers,
+  dropdowns, side navigation, tabs, tooltips, and more
+- ES module, CommonJS, browser IIFE, CSS, and TypeScript declaration outputs
+- Automatic component initialization with an opt-out mechanism
 
-The framework uses MaterializeCSS v2.2.2 as its foundation, which will be progressively updated and reshaped to match the M3 Expressive design language.
+## Requirements
 
-## Project Structure
+- [Node.js](https://nodejs.org/) 20 or newer
+- npm
+- Python 3.14 or newer and [uv](https://docs.astral.sh/uv/) to run the local
+  documentation site
 
+Python is not required to build or use the framework itself.
+
+## Getting started
+
+Clone the repository and install the JavaScript dependencies:
+
+```sh
+npm install
+npm run build
 ```
-src/scss/
-├── materialize.scss          # Entry point
-├── foundation/               # Design tokens, theme, variables, color palette, mixins, normalize, base
-├── utilities/                # Colors, typography, elevation, spacing, responsive, helpers
-├── layout/                   # Grid, footer, table
-├── components/               # 28 UI components (buttons, cards, appbar, modal, etc.)
-└── forms/                    # Input fields, radio buttons, checkboxes, switches, select, file input, range
+
+The compiled assets are written to `dist/`:
+
+```text
+dist/
+├── css/
+│   ├── expressive.css
+│   └── expressive.min.css
+├── js/
+│   ├── expressive.cjs
+│   ├── expressive.js
+│   ├── expressive.min.js
+│   └── expressive.mjs
+└── types/
 ```
 
-The framework loads in a layered dependency order: **foundation → utilities → layout → components → forms**, ensuring design tokens and variables are available before any component uses them.
+Source maps are produced alongside the CSS and JavaScript bundles.
 
-## Getting Started
+## Usage
 
-### Prerequisites
+### Browser bundle
 
-- [Sass](https://sass-lang.com/) (Dart Sass recommended — uses the modern `@use`/`@forward` module system)
+Include the compiled stylesheet and browser bundle, then initialize components
+after the page has loaded:
 
-### Installation
+```html
+<link rel="stylesheet" href="dist/css/expressive.min.css">
 
-Clone the repository:
+<ul class="collapsible">
+  <li>
+    <div class="collapsible-header">Details</div>
+    <div class="collapsible-body">ExpressiveCSS is ready.</div>
+  </li>
+</ul>
 
-```bash
-git clone https://github.com/BaezFJ/ExpressiveCSS.git
-cd ExpressiveCSS
+<script src="dist/js/expressive.min.js"></script>
+<script>
+  document.addEventListener('DOMContentLoaded', () => {
+    Expressive.AutoInit();
+  });
+</script>
 ```
 
-### Usage
+The browser bundle exposes the framework as the global `Expressive` object.
 
-Import the full framework in your Sass file:
+### ES modules
 
-```scss
-@use 'path/to/src/scss/materialize';
+Import the framework or individual components from the module build:
+
+```js
+import { AutoInit, Tooltip } from './dist/js/expressive.mjs';
+
+AutoInit();
+
+const element = document.querySelector('.custom-tooltip');
+Tooltip.init(element, { position: 'top' });
+```
+
+`AutoInit()` scans `document.body` by default. Pass a container to limit the
+scan, or add the `no-autoinit` class to an element that should be initialized
+manually:
+
+```js
+AutoInit(document.querySelector('#app'), {
+  Tooltip: { position: 'top' }
+});
 ```
 
-Or import only the layers you need:
+Importing the JavaScript bundle installs the framework's shared document
+behaviors, but it does not call `AutoInit()` automatically.
+
+### Sass
+
+Use the framework's Sass entry point in another Sass project:
 
 ```scss
-@use 'path/to/src/scss/foundation';
-@use 'path/to/src/scss/utilities';
-@use 'path/to/src/scss/components';
+@use "expressivecss/src/sass/expressive";
 ```
 
-### Compile
+When working directly in this repository, the entry point is
+`src/sass/expressive.scss`.
 
-```bash
-sass src/scss/materialize.scss dist/css/materialize.css
+### Themes
+
+ExpressiveCSS uses the `theme` attribute on the root element:
+
+```html
+<html lang="en" theme="light">
 ```
 
-## Components
+Switch themes at runtime by updating the attribute:
+
+```js
+document.documentElement.setAttribute('theme', 'dark');
+```
 
-ExpressiveCSS includes a wide range of UI components:
+## Development
 
-**Layout** — Grid, Footer, Table
+Available npm commands include:
 
-**Components** — Buttons, Cards, Navbar, Tabs, Modal, Dropdown, Sidenav, Collapsible, Carousel, Slider, Tooltip, Toast, Chips, Badges, Collection, Breadcrumb, Pagination, Parallax, Preloader, Pulse, Tap Target, Date Picker, Time Picker, Table of Contents, Material Box, Material Icons, Video
+| Command | Purpose |
+| --- | --- |
+| `npm run build` | Build all CSS, JavaScript, and declaration files |
+| `npm run build:css` | Build expanded and minified CSS |
+| `npm run build:js` | Build ESM, CommonJS, and browser bundles |
+| `npm run build:types` | Generate TypeScript declarations |
+| `npm run watch` | Watch Sass and TypeScript sources |
+| `npm run typecheck` | Check the TypeScript source without emitting files |
+| `npm test` | Build the ESM bundle and run the test suite |
+| `npm run clean` | Remove generated build output |
+
+Run the local documentation and smoke-test site in a second terminal:
+
+```sh
+uv sync
+uv run python docs/app.py
+```
 
-**Forms** — Input Fields, Radio Buttons, Checkboxes, Switches, Select, File Input, Range
+Then open `http://127.0.0.1:5000`. The Flask app serves assets directly from
+`dist/`, so changes made by `npm run watch` appear after a browser refresh.
 
-## Acknowledgments
+## Project structure
 
-ExpressiveCSS is built on top of **[MaterializeCSS v2.2.2](https://materializecss.github.io/materialize/)**, a modern responsive front-end framework based on Material Design. We are grateful to the MaterializeCSS team and its contributors for providing the solid foundation that this project builds upon.
+```text
+src/
+├── sass/        Design tokens, utilities, base styles, and component styles
+└── ts/          Core APIs, behaviors, plugins, and interactive components
+docs/            Local Flask documentation and build smoke test
+tests/           Node test runner and jsdom tests
+dist/            Generated distributable files
+```
+
+See [`src/sass/README.md`](src/sass/README.md) for Sass architecture and
+[`src/ts/README.md`](src/ts/README.md) for component conventions and testing
+guidance.
+
+## Testing
+
+Run the complete automated suite with:
+
+```sh
+npm test
+npm run typecheck
+```
 
-MaterializeCSS is licensed under the [MIT License](https://github.com/nicholasgasior/materialize/blob/v2-dev/LICENSE).
+Tests use Node's built-in test runner and jsdom. Because jsdom does not perform
+layout, component tests focus on DOM structure, classes, content, and lifecycle
+behavior rather than geometry or visual transitions.
 
-## License
+## Contributing
 
-This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
+Keep generated files out of commits, add tests for behavior changes, and run
+both the test suite and type checker before submitting a change. New JavaScript
+components must be exported from `src/ts/components/index.ts`; components that
+support automatic initialization must also be registered in
+`src/ts/components/registry.ts`.