Skip to content

positive-intentions/dim

Repository files navigation

Dim Framework Logo

Dim Framework

A React-inspired functional web components framework

Build modern web applications with familiar React-like syntax, powered by native Web Components

GitHub stars GitHub forks GitHub issues License Staging gh-pages-build-deployment


🌟 Overview

Dim is a lightweight framework that brings React's component model and hooks to native Web Components. Write familiar functional components with hooks while leveraging the power of web standards.

⚠️ Experimental: This framework is in early development and is not production-ready. It's provided for educational and experimental purposes.

✨ Features

  • 🎯 React-like DX - Familiar hooks API (useState, useEffect, useMemo, etc.)
  • πŸ”§ Web Standards - Built on native Web Components and Shadow DOM
  • 🎨 Scoped Styling - CSS-in-JS with automatic style isolation
  • πŸ“¦ Zero Dependencies - Pure JavaScript, no build step required
  • πŸš€ Lightweight - Minimal overhead on top of native APIs
  • πŸ’Ύ State Persistence - Built-in global state management with useStore

πŸš€ Getting Started

Quick Example

import { html, css, define, useState, useStyle } from "@dim/core";

// Create a component
const Counter = (props, { useState, html, css, useStyle }) => {
  const [count, setCount] = useState(0);

  useStyle(css`
    .counter {
      padding: 2rem;
      text-align: center;
    }

    button {
      background: #029cfd;
      color: white;
      border: none;
      padding: 0.5rem 1rem;
      border-radius: 4px;
      cursor: pointer;
    }
  `);

  return html`
    <div class="counter">
      <h2>Count: ${count}</h2>
      <button @click="${() => setCount(count + 1)}">Increment</button>
    </div>
  `;
};

// Register as custom element
define({ tag: "my-counter", component: Counter });

// Use it
// <my-counter></my-counter>

πŸ“š Core Concepts

Hooks

Dim provides React-like hooks for managing component logic:

useState - Local State Management

const [value, setValue] = useState(initialValue);

useEffect - Side Effects

useEffect(() => {
  // Effect logic
  return () => {
    // Cleanup
  };
}, [dependencies]);

useStyle - Scoped CSS

useStyle(css`
  .my-class {
    color: blue;
  }
`);

useScope - Component Composition

useScope({
  "child-component": ChildComponent,
});

useMemo - Memoized Values

const expensive = useMemo(() => {
  return computeExpensive(value);
}, [value]);

useRef - DOM References

const inputRef = useRef();
// Access via inputRef.current

useStore - Global State

const {
  user: [user, setUser],
} = useStore({
  user: { name: "John" },
});

πŸ’‘ Examples

Todo List

const TodoList = (props, { useState, html, css, useStyle }) => {
  const [todos, setTodos] = useState([]);
  const [input, setInput] = useState("");

  const addTodo = () => {
    if (input.trim()) {
      setTodos([
        ...todos,
        {
          id: Date.now(),
          text: input,
          done: false,
        },
      ]);
      setInput("");
    }
  };

  return html`
    <div>
      <input
        .value="${input}"
        @input="${(e) => setInput(e.target.value)}"
        @keydown="${(e) => e.key === "Enter" && addTodo()}"
      />
      <button @click="${addTodo}">Add</button>

      <ul>
        ${todos.map(
          (todo) => html`
            <li class="${todo.done ? "done" : ""}">
              <input
                type="checkbox"
                .checked="${todo.done}"
                @change="${() => toggleTodo(todo.id)}"
              />
              ${todo.text}
            </li>
          `
        )}
      </ul>
    </div>
  `;
};

πŸ“– Documentation

The framework includes comprehensive documentation through Storybook:

Main Sections

  1. Getting Started - Introduction and quick start guide
  2. Core Concepts - Deep dive into hooks and component architecture
  3. Tutorial - Step-by-step guide to building applications
  4. Examples - Real-world patterns and implementations
  5. API Reference - Detailed documentation for each hook

Hook Categories

  • State Management: useState, useStore
  • Effects & Lifecycle: useEffect, useRef
  • Performance: useMemo
  • Styling: useStyle
  • Composition: useScope

Visit the live documentation for interactive examples and detailed guides.

πŸ› οΈ Development

Setup

# Clone the repository
git clone https://github.com/positive-intentions/dim.git

# Install dependencies
npm install

# Start Storybook dev server
npm run storybook

# Build for production
npm run build

Project Structure

dim/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ core/
β”‚   β”‚   β”œβ”€β”€ dim.ts          # Main framework code
β”‚   β”‚   β”œβ”€β”€ mini-lit.js     # Lit wrapper
β”‚   β”‚   └── storage-manager.js
β”‚   └── stories/
β”‚       β”œβ”€β”€ *.stories.js    # Main documentation
β”‚       β”œβ”€β”€ hooks/          # Hook examples
β”‚       β”œβ”€β”€ advanced/       # Advanced patterns
β”‚       └── tutorial/       # Step-by-step guides
β”œβ”€β”€ public/
└── README.md

βš–οΈ License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0) - see the LICENSE file for details. This means you are free to use, modify, and distribute this software, but any derivative works must also be licensed under GPL-3.0.

πŸ™ Acknowledgments

  • Inspired by React's component model and hooks
  • Built on top of Lit for reactive Web Components
  • Community feedback

Dim is brought to you by positive-intentions. Built with positivity.