first commit

README.md

@@ -0,0 +1,80 @@
+# wc-timer
+
+A lightweight, dependency-free Web Component for countdowns and elapsed time. It uses the native `Intl` API for formatting and supports automatic language detection.
+
+## Features
+
+* **Zero Dependencies**: Built with standard Web Components API.
+* **Smart Formatting**: Supports various presets like `hms`, `dhms`, or `ydhms`.
+* **Performance**: Uses a shared global ticker (TickHub) to sync all instances and save CPU.
+* **Light DOM**: Renders text directly, making it easy to style with global CSS.
+* **Responsive**: Automatically updates when attributes change.
+
+## Installation
+
+```bash
+npm install wc-timer
+
+```
+
+## Usage
+
+1. **Import the script**:
+
+```javascript
+import 'wc-timer';
+// Or via script tag
+// <script type="module" src="path/to/wc-timer.js"></script>
+
+```
+
+2. **Use the tag in HTML**:
+
+```html
+<wc-timer target="2025-12-31T23:59:59Z"></wc-timer>
+
+<wc-timer 
+  target="2026-01-01T00:00:00Z" 
+  preset="dhms" 
+  labels="short" 
+  compact
+  locale="en-US">
+</wc-timer>
+
+```
+
+## API Reference
+
+### Attributes
+
+| Attribute | Type | Default | Description |
+| --- | --- | --- | --- |
+| `target` | `ISO 8601` | `now` | The target date/time (e.g., `2025-12-31T23:59:59Z`). |
+| `preset` | `string` | `auto` | Format preset: `auto`, `hms`, `dhms`, `ydhms`, `date`. |
+| `labels` | `string` | `long` | Unit labels: `none` (00:00:00), `short` (1h 5m), `long` (1 hour 5 minutes). |
+| `compact` | `boolean` | `false` | If present, hides zero-value units (e.g., skips "0 years"). |
+| `locale` | `BCP 47` | `auto` | Forces a specific language (e.g., `pl`, `en`, `de`). Defaults to browser settings. |
+
+### JavaScript Properties
+
+All attributes are reflected as properties on the DOM element.
+
+```javascript
+const el = document.querySelector('wc-timer');
+
+// Update target dynamically
+el.target = new Date('2030-01-01');
+
+// Change configuration
+el.preset = 'ydhms';
+el.compact = true;
+
+```
+
+## Browser Support
+
+Works in all modern browsers supporting Web Components and `Intl.DurationFormat` (or falls back gracefully).
+
+## License
+
+MIT