diffdown.com
Diffdown is a real-time collaborative Markdown editor/previewer built on the AT Protocol
diffdown.com
1<!-- To edit this file, edit /src/README.md, not /README.md -->
2
3# style-mod
4
5Minimal CSS module shim for generating CSS rules for sets of style
6-declarations and attaching such a set to a document or shadow root.
7
8Using it would look something like this:
9
10```javascript
11const {StyleModule} = require("style-mod")
12const myModule = new StyleModule({
13 "#main": {
14 fontFamily: "Georgia, 'Nimbus Roman No9 L'",
15 margin: "0"
16 },
17 ".callout": {
18 color: "red",
19 fontWeight: "bold",
20 "&:hover": {color: "orange"}
21 }
22})
23StyleModule.mount(document, myModule)
24```
25
26This code is open source, released under an MIT license.
27
28## Documentation
29
30### class StyleModule
31
32Style modules encapsulate a set of CSS rules defined from
33JavaScript. Their definitions are only available in a given DOM
34root after it has been _mounted_ there with `StyleModule.mount`.
35
36Style modules should be created once and stored somewhere, as
37opposed to re-creating them every time you need them. The amount of
38CSS rules generated for a given DOM root is bounded by the amount
39of style modules that were used. So to avoid leaking rules, don't
40create these dynamically, but treat them as one-time allocations.
41
42 * `new `**`StyleModule`**`(spec: Object< Style >, options: ?{finish: ?fn(string) → string})`\
43 Create a style module from the given spec.
44
45 When `finish` is given, it is called on regular (non-`@`)
46 selectors (after `&` expansion) to compute the final selector.
47
48 * **`getRules`**`() → string`\
49 Returns a string containing the module's CSS rules.
50
51 * `static `**`newName`**`() → string`\
52 Generate a new unique CSS class name.
53
54 * `static `**`mount`**`(root: Document | ShadowRoot, modules: [StyleModule] | StyleModule, options: ?{nonce: ?string})`\
55 Mount the given set of modules in the given DOM root, which ensures
56 that the CSS rules defined by the module are available in that
57 context.
58
59 Rules are only added to the document once per root.
60
61 Rule order will follow the order of the modules, so that rules from
62 modules later in the array take precedence of those from earlier
63 modules. If you call this function multiple times for the same root
64 in a way that changes the order of already mounted modules, the old
65 order will be changed.
66
67 If a Content Security Policy nonce is provided, it is added to
68 the `<style>` tag generated by the library.
69
70
71Where the `Style` type is defined as:
72
73 * **`Style`**`: Object< Style | string >`\
74 A style is an object that, in the simple case, maps CSS property
75 names to strings holding their values, as in `{color: "red",
76 fontWeight: "bold"}`. The property names can be given in
77 camel-case—the library will insert a dash before capital letters
78 when converting them to CSS.
79
80 If you include an underscore in a property name, it and everything
81 after it will be removed from the output, which can be useful when
82 providing a property multiple times, for browser compatibility
83 reasons.
84
85 A property in a style object can also be a sub-selector, which
86 extends the current context to add a pseudo-selector or a child
87 selector. Such a property should contain a `&` character, which
88 will be replaced by the current selector. For example `{"&:before":
89 {content: '"hi"'}}`. Sub-selectors and regular properties can
90 freely be mixed in a given object. Any property containing a `&` is
91 assumed to be a sub-selector.
92
93 Finally, a property can specify an @-block to be wrapped around the
94 styles defined inside the object that's the property's value. For
95 example to create a media query you can do `{"@media screen and
96 (min-width: 400px)": {...}}`.
97
98