protos 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 396bd8424d9be7d44d3d2ebcd27fb5bbcfb8c06de62a9bb1b8cf01fc50d9214e
-  data.tar.gz: f536874ad166bc77a0817199bc62e6f5505865a61beae8c22afad7b4b6b219a7
+  metadata.gz: 5f0cbce70d804580aab642e9b099b3eb3de37af48c39314fe396b84db192c60c
+  data.tar.gz: 21a82750e78f2325286bdbf4c1d741ce9ab8ccb79d946eca324ef128ec1a0604
 SHA512:
-  metadata.gz: 158b684976d5124c7e6cb2b779fa85305a42b44a9578ddaf7a6b5960ddecc07da71c96734cd1cd663ee2d9f4f65b14a4a2f1e8493293639dfe15eb5640c22f89
-  data.tar.gz: 111f6aca758b7f21cc7a3021448c4d323e13699d40533b43b10fc39a492c7d9a62d48d2a761c57af32b5c3bfd0d6ef7dd32cf9ddc9de22d3bec7f99c54afe449
+  metadata.gz: 926c96c62de37324ea452b002c533dd61a32c1a5319415d8ef6a4592d1854325e58ad2b93e03d9b7f79c1f9b3ff8ec742f0d9bc4aed1c5caa651b0a747a8bd8d
+  data.tar.gz: 21ece1afc62a9d5ee521eebbda4347e6111d343965807e80b443b1ea607c43bf6411db97dedb8d395ae332054eaf232932faf1ac850f65e7b5718c8dff01610b

data/README.md

@@ -2,8 +2,64 @@
 
 A UI component library for Phlex using daisyui.
 
+All components avoid using `Phlex::DeferredRender` so you can reorder components
+exactly how you like them.
+
+Components are easy to style, positioning them is usually done through the
+`class` option which applies the style to the outer most container of the
+component:
+
+```ruby
+render Protos::Avatar.new(class: "my-lg") do |avatar|
+  # ...
+end
+```
+
+But they are also extensible to all styles by injecting a `theme` into the
+component:
+
+```ruby
+render Protos::Avatar.new(theme: {
+    container: "my-lg",
+    figure: "p-sm" # Apply this padding to the image container
+}) do |avatar|
+  # ...
+end
+```
+
+You can even override or negate certain parts of the theme:
+
+```ruby
+render Protos::Avatar.new(theme: {
+    container!: "my-lg", # Override the original container style
+    "!figure": "p-sm"    # Remove this class from the figure style
+}) do |avatar|
+  # ...
+end
+```
+
+If the component uses a stimulus controller on the data component, or any other
+default attributes you can safely add to them without overriding:
+
+```ruby
+render Protos::Avatar.new(data: { controller: "my-controller" }) do |avatar|
+  # ...
+end
+```
+
+This will add your attributes without removing the important ones that help the
+components be accessible.
+
 Protos uses a set of conventions that make it easier to work with tailwindcss
-and components in Phlex which you can use by inheriting from the base component.
+and components in Phlex which you can use in your own components by inheriting 
+from the base component.
+
+This adds:
+1. extends `Dry::Initializer` to easily add initialization params and options
+2. adds `attrs` which merges html attributes onto defaults
+3. adds `default_attrs` for default html attributes on a component
+4. adds `theme` for default styles hash
+5. adds `css` for accessing theme slots
 
 You can find this example in `examples/navbar.rb` which you can run with `ruby
 examples/navbar.rb`:
@@ -82,7 +138,10 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-Setup tailwindcss:
+Setup tailwindcss to add the protos path to your content.
+
+Protos also uses semantic spacing such as `p-sm` or `m-md` instead of set
+numbers so you can easily choose the spacing you want.
 
 ```js
 // tailwind.config.js
@@ -96,6 +155,26 @@ module.exports = {
     "./app/views/**/*.{rb,html,html.erb,erb}",
     protos_path
   ],
+  theme: {
+    extend: {
+      spacing: {
+        xs: "var(--spacing-xs)",
+        sm: "var(--spacing-sm)",
+        md: "var(--spacing-md)",
+        lg: "var(--spacing-lg)",
+        xl: "var(--spacing-xl)",
+      },
+      // If you use % based spacing you might want different spacing
+      // for any vertical gaps to prevent overflow
+      gap: {
+        xs: "var(--spacing-gap-xs)",
+        sm: "var(--spacing-gap-sm)",
+        md: "var(--spacing-gap-md)",
+        lg: "var(--spacing-gap-lg)",
+        xl: "var(--spacing-gap-xl)",
+      },
+    },
+  }
   // ....
 }
 ```
@@ -127,6 +206,34 @@ render Protos::Card.new(class: "bg-base-100") do |card|
 end
 ```
 
+A good idea would be to encapsulate these proto components with your own
+components as a wrapper. For example you could use `Proto::List` to create your
+own list and even use `Phlex::DeferredRender` to make the API more convenient.
+
+```ruby
+module Ui
+  class List < Protos::Component
+    include Protos::Typography
+    include Phlex::DeferredRender
+
+    def template
+      article(**attrs) do
+        header class: css[:header] do
+          h3(size: :md) { title }
+          nav { render_actions }
+        end
+
+        render Protos::List do |list|
+          items.each do |item|
+            render list.item { render item }
+          end
+        end
+      end
+    end
+  end
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/lib/protos/list.rb

@@ -14,7 +14,7 @@ module Protos
 
     private
 
-    def css
+    def theme
       {
         container: tokens(
           "join",

data/lib/protos/timeline.rb

@@ -26,7 +26,7 @@ module Protos
 
     private
 
-    def css
+    def theme
       {
         container: tokens(
           "timeline",

data/lib/protos/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Protos
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protos
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Nolan J Tait