@gtkx/css 0.9.3 → 0.10.0

package/README.md

@@ -1,47 +1,43 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/eugeniodepalo/gtkx/HEAD/logo.svg" alt="GTKX Logo" width="128" height="128">
+  <img src="https://raw.githubusercontent.com/eugeniodepalo/gtkx/main/logo.svg" alt="GTKX" width="80" height="80">
 </p>
 
 <h1 align="center">GTKX</h1>
 
 <p align="center">
-  <strong>Build native GTK4 desktop apps with React</strong>
+  <strong>Build native GTK4 desktop applications with React and TypeScript.</strong>
 </p>
 
 <p align="center">
-  <a href="https://eugeniodepalo.github.io/gtkx">Documentation</a> ·
-  <a href="#quick-start">Quick Start</a> ·
-  <a href="#examples">Examples</a> ·
-  <a href="#contributing">Contributing</a>
+  <a href="https://www.npmjs.com/package/@gtkx/react"><img src="https://img.shields.io/npm/v/@gtkx/react.svg" alt="npm version"></a>
+  <a href="https://github.com/eugeniodepalo/gtkx/actions"><img src="https://img.shields.io/github/actions/workflow/status/eugeniodepalo/gtkx/ci.yml" alt="CI"></a>
+  <a href="https://github.com/eugeniodepalo/gtkx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MPL--2.0-blue.svg" alt="License"></a>
+  <a href="https://github.com/eugeniodepalo/gtkx/discussions"><img src="https://img.shields.io/badge/discussions-GitHub-blue" alt="GitHub Discussions"></a>
 </p>
 
 ---
 
-GTKX lets you build native Linux desktop applications using React and TypeScript. Write familiar React code that renders as native GTK4 widgets—no Electron, no web views.
-
-## Features
-
-- **React** — Hooks, state, props, and components you already know
-- **HMR** — Edit code and see changes instantly via Vite
-- **Native** — Direct FFI bindings to GTK4 via Rust and libffi
-- **CLI** — `npx @gtkx/cli@latest create` scaffolds a ready-to-go project
-- **CSS-in-JS** — Emotion-style `css` template literals for GTK styling
-- **Testing** — Testing Library-style `screen`, `userEvent`, and queries
+GTKX lets you write Linux desktop applications using React. Your components render as native GTK4 widgets through a Rust FFI bridge—no webviews, no Electron, just native performance with the developer experience you already know.
 
 ## Quick Start
 
 ```bash
-npx @gtkx/cli@latest create my-app
+npx @gtkx/cli create my-app
 cd my-app
 npm run dev
 ```
 
-Edit your code and see changes instantly—no restart needed.
-
-### Example
+## Example
 
 ```tsx
-import { render, ApplicationWindow, Box, Button, quit } from "@gtkx/react";
+import {
+  GtkApplicationWindow,
+  GtkBox,
+  GtkButton,
+  GtkLabel,
+  quit,
+  render,
+} from "@gtkx/react";
 import * as Gtk from "@gtkx/ffi/gtk";
 import { useState } from "react";
 
@@ -49,67 +45,59 @@ const App = () => {
   const [count, setCount] = useState(0);
 
   return (
-    <ApplicationWindow title="Counter" onCloseRequest={quit}>
-      <Box orientation={Gtk.Orientation.VERTICAL} spacing={12}>
-        {`Count: ${count}`}
-        <Button label="Increment" onClicked={() => setCount((c) => c + 1)} />
-      </Box>
-    </ApplicationWindow>
+    <GtkApplicationWindow
+      title="Counter"
+      defaultWidth={300}
+      defaultHeight={200}
+      onCloseRequest={quit}
+    >
+      <GtkBox
+        orientation={Gtk.Orientation.VERTICAL}
+        spacing={20}
+        valign={Gtk.Align.CENTER}
+      >
+        <GtkLabel label={`Count: ${count}`} cssClasses={["title-1"]} />
+        <GtkButton label="Increment" onClicked={() => setCount((c) => c + 1)} />
+      </GtkBox>
+    </GtkApplicationWindow>
   );
 };
 
-render(<App />, "org.example.Counter");
+render(<App />, "com.example.counter");
 ```
 
-## Styling
-
-```tsx
-import { css } from "@gtkx/css";
-import { Button } from "@gtkx/react";
-
-const primary = css`
-  padding: 16px 32px;
-  border-radius: 24px;
-  background: linear-gradient(135deg, #3584e4, #9141ac);
-  color: white;
-`;
-
-<Button label="Click me" cssClasses={[primary]} />;
-```
-
-## Testing
-
-```tsx
-import { cleanup, render, screen, userEvent } from "@gtkx/testing";
-import * as Gtk from "@gtkx/ffi/gtk";
-
-afterEach(() => cleanup());
+## Features
 
-test("increments count", async () => {
-  await render(<App />);
+- **React 19** — Hooks, concurrent features, and the component model you know
+- **Native GTK4 widgets** — Real native controls, not web components in a webview
+- **Adwaita support** — Modern GNOME styling with Libadwaita components
+- **Hot Module Replacement** — Fast refresh during development
+- **TypeScript first** — Full type safety with auto-generated bindings
+- **CSS-in-JS styling** — Familiar styling patterns adapted for GTK
+- **Testing utilities** — Component testing similar to Testing Library
 
-  const button = await screen.findByRole(Gtk.AccessibleRole.BUTTON, {
-    name: "Increment",
-  });
+## Examples
 
-  await userEvent.click(button);
+Explore complete applications in the [`examples/`](./examples) directory:
 
-  await screen.findByText("Count: 1");
-});
-```
+- **[gtk-demo](./examples/gtk-demo)** — Full replica of the official GTK demo app
+- **[hello-world](./examples/hello-world)** — Minimal application showing a counter
+- **[todo](./examples/todo)** — Full-featured todo application with Adwaita styling and testing
+- **[deploying](./examples/deploying)** — Example of packaging and distributing a GTKX app
 
-## Requirements
+## Documentation
 
-- Node.js 20+ (Deno support experimental)
-- GTK4 Runtime (`gtk4` on Fedora, `libgtk-4-1` on Ubuntu)
+Visit [https://eugeniodepalo.github.io/gtkx](https://eugeniodepalo.github.io/gtkx/) for the full documentation.
 
 ## Contributing
 
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Contributions are welcome! Please see the [contributing guidelines](./CONTRIBUTING.md) and check out the [good first issues](https://github.com/eugeniodepalo/gtkx/labels/good%20first%20issue).
+
+## Community
 
-- [Report a bug](https://github.com/eugeniodepalo/gtkx/issues/new?template=bug_report.md)
-- [Request a feature](https://github.com/eugeniodepalo/gtkx/issues/new?template=feature_request.md)
+- [GitHub Discussions](https://github.com/eugeniodepalo/gtkx/discussions) — Questions, ideas, and general discussion
+- [Issue Tracker](https://github.com/eugeniodepalo/gtkx/issues) — Bug reports and feature requests
 
 ## License
 
-[MPL-2.0](LICENSE)
+[MPL-2.0](./LICENSE)

package/dist/css.d.ts

@@ -1,48 +1,93 @@
 import type { CSSInterpolation } from "@emotion/serialize";
+/**
+ * Branded type for CSS class names generated by {@link css}.
+ */
 type CSSClassName = string & {
     __brand: "css";
 };
 /**
- * Creates a CSS class from styles and injects them into GTK.
- * Works like Emotion's css function but outputs to GTK's CssProvider.
+ * Creates a CSS class from style definitions.
+ *
+ * Uses Emotion's CSS-in-JS system adapted for GTK CSS. Supports nested selectors
+ * using `&` for the parent selector reference.
+ *
+ * @param args - CSS style definitions (objects, template literals, or interpolations)
+ * @returns A unique class name to use with `cssClasses` prop
  *
  * @example
  * ```tsx
- * const buttonStyle = css`
- *   background: @theme_bg_color;
- *   padding: 12px;
- *   border-radius: 6px;
- * `;
+ * import { css } from "@gtkx/css";
+ *
+ * const buttonStyle = css({
+ *   padding: "8px 16px",
+ *   borderRadius: "4px",
+ *   "&:hover": {
+ *     backgroundColor: "@accent_bg_color",
+ *   },
+ * });
  *
- * <Button cssClasses={[buttonStyle]}>Styled Button</Button>
+ * <GtkButton cssClasses={[buttonStyle]} label="Styled Button" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Template literal syntax
+ * const labelStyle = css`
+ *   font-size: 14px;
+ *   color: @theme_text_color;
+ * `;
  * ```
+ *
+ * @see {@link cx} for combining class names
+ * @see {@link injectGlobal} for global styles
  */
 export declare const css: (...args: CSSInterpolation[]) => CSSClassName;
 /**
- * Merges multiple class names, filtering out falsy values.
+ * Combines multiple class names into a single space-separated string.
+ *
+ * Filters out falsy values, allowing conditional class application.
+ *
+ * @param classNames - Class names, booleans, undefined, or null values
+ * @returns Space-separated string of valid class names
  *
  * @example
  * ```tsx
- * const combined = cx(baseStyle, isActive && activeStyle, 'manual-class');
- * <Button cssClasses={[combined]}>Button</Button>
+ * import { css, cx } from "@gtkx/css";
+ *
+ * const base = css({ padding: "8px" });
+ * const active = css({ backgroundColor: "@accent_bg_color" });
+ *
+ * <GtkButton
+ *   cssClasses={[cx(base, isActive && active, "custom-class")]}
+ *   label="Button"
+ * />
  * ```
  */
 export declare const cx: (...classNames: (string | boolean | undefined | null)[]) => string;
 /**
- * Injects global CSS styles.
- * Note: In GTK, these styles apply to all widgets on the display.
+ * Injects global CSS styles without a wrapping class.
+ *
+ * Use for application-wide styles, CSS variables, or styling native GTK widgets.
+ *
+ * @param args - CSS style definitions
  *
  * @example
  * ```tsx
+ * import { injectGlobal } from "@gtkx/css";
+ *
  * injectGlobal`
  *   window {
- *     background: @theme_bg_color;
+ *     background-color: @theme_bg_color;
  *   }
- *   button {
- *     border-radius: 6px;
+ *
+ *   .title-1 {
+ *     font-size: 24px;
+ *     font-weight: bold;
  *   }
  * `;
  * ```
+ *
+ * @see {@link css} for scoped class-based styles
  */
 export declare const injectGlobal: (...args: CSSInterpolation[]) => void;
 export {};

package/dist/css.js

@@ -51,19 +51,40 @@ function expandNestedRules(styles, className) {
     return allRules.join("\n");
 }
 /**
- * Creates a CSS class from styles and injects them into GTK.
- * Works like Emotion's css function but outputs to GTK's CssProvider.
+ * Creates a CSS class from style definitions.
+ *
+ * Uses Emotion's CSS-in-JS system adapted for GTK CSS. Supports nested selectors
+ * using `&` for the parent selector reference.
+ *
+ * @param args - CSS style definitions (objects, template literals, or interpolations)
+ * @returns A unique class name to use with `cssClasses` prop
  *
  * @example
  * ```tsx
- * const buttonStyle = css`
- *   background: @theme_bg_color;
- *   padding: 12px;
- *   border-radius: 6px;
- * `;
+ * import { css } from "@gtkx/css";
+ *
+ * const buttonStyle = css({
+ *   padding: "8px 16px",
+ *   borderRadius: "4px",
+ *   "&:hover": {
+ *     backgroundColor: "@accent_bg_color",
+ *   },
+ * });
+ *
+ * <GtkButton cssClasses={[buttonStyle]} label="Styled Button" />
+ * ```
  *
- * <Button cssClasses={[buttonStyle]}>Styled Button</Button>
+ * @example
+ * ```tsx
+ * // Template literal syntax
+ * const labelStyle = css`
+ *   font-size: 14px;
+ *   color: @theme_text_color;
+ * `;
  * ```
+ *
+ * @see {@link cx} for combining class names
+ * @see {@link injectGlobal} for global styles
  */
 export const css = (...args) => {
     const cache = getGtkCache();
@@ -78,30 +99,51 @@ export const css = (...args) => {
     return className;
 };
 /**
- * Merges multiple class names, filtering out falsy values.
+ * Combines multiple class names into a single space-separated string.
+ *
+ * Filters out falsy values, allowing conditional class application.
+ *
+ * @param classNames - Class names, booleans, undefined, or null values
+ * @returns Space-separated string of valid class names
  *
  * @example
  * ```tsx
- * const combined = cx(baseStyle, isActive && activeStyle, 'manual-class');
- * <Button cssClasses={[combined]}>Button</Button>
+ * import { css, cx } from "@gtkx/css";
+ *
+ * const base = css({ padding: "8px" });
+ * const active = css({ backgroundColor: "@accent_bg_color" });
+ *
+ * <GtkButton
+ *   cssClasses={[cx(base, isActive && active, "custom-class")]}
+ *   label="Button"
+ * />
  * ```
  */
 export const cx = (...classNames) => classNames.filter((cn) => typeof cn === "string" && cn.length > 0).join(" ");
 /**
- * Injects global CSS styles.
- * Note: In GTK, these styles apply to all widgets on the display.
+ * Injects global CSS styles without a wrapping class.
+ *
+ * Use for application-wide styles, CSS variables, or styling native GTK widgets.
+ *
+ * @param args - CSS style definitions
  *
  * @example
  * ```tsx
+ * import { injectGlobal } from "@gtkx/css";
+ *
  * injectGlobal`
  *   window {
- *     background: @theme_bg_color;
+ *     background-color: @theme_bg_color;
  *   }
- *   button {
- *     border-radius: 6px;
+ *
+ *   .title-1 {
+ *     font-size: 24px;
+ *     font-weight: bold;
  *   }
  * `;
  * ```
+ *
+ * @see {@link css} for scoped class-based styles
  */
 export const injectGlobal = (...args) => {
     const cache = getGtkCache();

package/dist/style-sheet.js

@@ -13,12 +13,9 @@ const flushPendingStyles = () => {
 };
 const resetGtkState = () => {
     isGtkReady = false;
-    // Re-register the start listener for the next start() call
     events.once("start", flushPendingStyles);
 };
-// Initial registration
 events.once("start", flushPendingStyles);
-// Handle stop to reset state and prepare for potential restart
 events.on("stop", resetGtkState);
 export class StyleSheet {
     key;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/css",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "Emotion-style CSS-in-JS for GTKX applications",
   "keywords": [
     "gtk",
@@ -35,7 +35,7 @@
   "dependencies": {
     "@emotion/cache": "^11.14.0",
     "@emotion/serialize": "^1.3.3",
-    "@gtkx/ffi": "0.9.3"
+    "@gtkx/ffi": "0.10.0"
   },
   "scripts": {
     "build": "tsc -b && cp ../../README.md .",