ozdenui 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (149) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +14 -0
  3. data/NOTICE +5 -0
  4. data/README.md +242 -0
  5. data/exe/ozdenui +17 -0
  6. data/lib/ozdenui/AGENTS.md +210 -0
  7. data/lib/ozdenui/COMPONENTS.md +3017 -0
  8. data/lib/ozdenui/app.rb +749 -0
  9. data/lib/ozdenui/command.rb +107 -0
  10. data/lib/ozdenui/components.rb +368 -0
  11. data/lib/ozdenui/dialogs.rb +212 -0
  12. data/lib/ozdenui/files.rb +124 -0
  13. data/lib/ozdenui/icon.png +0 -0
  14. data/lib/ozdenui/kit.json +1 -0
  15. data/lib/ozdenui/kit.rb +115 -0
  16. data/lib/ozdenui/look.rb +229 -0
  17. data/lib/ozdenui/objects.rb +652 -0
  18. data/lib/ozdenui/server.rb +270 -0
  19. data/lib/ozdenui/values.rb +273 -0
  20. data/lib/ozdenui/version.rb +15 -0
  21. data/lib/ozdenui/web/basic/LICENSE +14 -0
  22. data/lib/ozdenui/web/basic/basic.min.css +1 -0
  23. data/lib/ozdenui/web/basic/basic.min.js +78 -0
  24. data/lib/ozdenui/web/basic/font/open-sans/LICENSE.txt +206 -0
  25. data/lib/ozdenui/web/basic/font/open-sans/OpenSans-Bold.ttf +0 -0
  26. data/lib/ozdenui/web/basic/font/open-sans/OpenSans-Regular.ttf +0 -0
  27. data/lib/ozdenui/web/basic/scroll-bar.min.js +3 -0
  28. data/lib/ozdenui/web/bridge.js +584 -0
  29. data/lib/ozdenui/web/comp/accordion.js +659 -0
  30. data/lib/ozdenui/web/comp/action-button/add.png +0 -0
  31. data/lib/ozdenui/web/comp/action-button.js +521 -0
  32. data/lib/ozdenui/web/comp/action-tab-bar.js +383 -0
  33. data/lib/ozdenui/web/comp/app-bar.js +237 -0
  34. data/lib/ozdenui/web/comp/badge.js +292 -0
  35. data/lib/ozdenui/web/comp/bottom-bar.js +555 -0
  36. data/lib/ozdenui/web/comp/breadcrumbs.js +524 -0
  37. data/lib/ozdenui/web/comp/canvas.js +652 -0
  38. data/lib/ozdenui/web/comp/chat-view.js +827 -0
  39. data/lib/ozdenui/web/comp/check-box.js +490 -0
  40. data/lib/ozdenui/web/comp/code-editor.js +965 -0
  41. data/lib/ozdenui/web/comp/color-picker.js +636 -0
  42. data/lib/ozdenui/web/comp/context-menu.js +951 -0
  43. data/lib/ozdenui/web/comp/currency-field.js +209 -0
  44. data/lib/ozdenui/web/comp/data-table/arrow.svg +2 -0
  45. data/lib/ozdenui/web/comp/data-table.js +937 -0
  46. data/lib/ozdenui/web/comp/date-picker.js +1055 -0
  47. data/lib/ozdenui/web/comp/dialog.js +992 -0
  48. data/lib/ozdenui/web/comp/email-field.js +65 -0
  49. data/lib/ozdenui/web/comp/file-picker.js +920 -0
  50. data/lib/ozdenui/web/comp/filters.js +807 -0
  51. data/lib/ozdenui/web/comp/form.js +602 -0
  52. data/lib/ozdenui/web/comp/full-screen-select/arrow.svg +2 -0
  53. data/lib/ozdenui/web/comp/full-screen-select/cancel.svg +2 -0
  54. data/lib/ozdenui/web/comp/full-screen-select.js +614 -0
  55. data/lib/ozdenui/web/comp/gauge.js +439 -0
  56. data/lib/ozdenui/web/comp/graph-box.js +3911 -0
  57. data/lib/ozdenui/web/comp/grid-group.js +185 -0
  58. data/lib/ozdenui/web/comp/hold-to-confirm-button/trash-red.png +0 -0
  59. data/lib/ozdenui/web/comp/hold-to-confirm-button/trash.png +0 -0
  60. data/lib/ozdenui/web/comp/hold-to-confirm-button.js +289 -0
  61. data/lib/ozdenui/web/comp/image-view.js +598 -0
  62. data/lib/ozdenui/web/comp/item-list.js +1740 -0
  63. data/lib/ozdenui/web/comp/json-editor.js +3221 -0
  64. data/lib/ozdenui/web/comp/json-view.js +597 -0
  65. data/lib/ozdenui/web/comp/label-editor.js +1140 -0
  66. data/lib/ozdenui/web/comp/left-menu/data-table.png +0 -0
  67. data/lib/ozdenui/web/comp/left-menu/home.png +0 -0
  68. data/lib/ozdenui/web/comp/left-menu/reports.png +0 -0
  69. data/lib/ozdenui/web/comp/left-menu/setting.png +0 -0
  70. data/lib/ozdenui/web/comp/left-menu.js +548 -0
  71. data/lib/ozdenui/web/comp/line-progress-bar.js +343 -0
  72. data/lib/ozdenui/web/comp/loading-screen.js +413 -0
  73. data/lib/ozdenui/web/comp/log-view.js +530 -0
  74. data/lib/ozdenui/web/comp/login-page.js +685 -0
  75. data/lib/ozdenui/web/comp/markdown-view.js +1045 -0
  76. data/lib/ozdenui/web/comp/menu-bar.js +624 -0
  77. data/lib/ozdenui/web/comp/mini-graph-box.js +492 -0
  78. data/lib/ozdenui/web/comp/minimal-accent.js +208 -0
  79. data/lib/ozdenui/web/comp/notice.js +229 -0
  80. data/lib/ozdenui/web/comp/number-field.js +128 -0
  81. data/lib/ozdenui/web/comp/numeric-keyboard.js +298 -0
  82. data/lib/ozdenui/web/comp/page-control.js +762 -0
  83. data/lib/ozdenui/web/comp/page-header.js +191 -0
  84. data/lib/ozdenui/web/comp/password-field/hide-btn.png +0 -0
  85. data/lib/ozdenui/web/comp/password-field/hide-btn2.png +0 -0
  86. data/lib/ozdenui/web/comp/password-field/show-btn.png +0 -0
  87. data/lib/ozdenui/web/comp/password-field/show-btn2.png +0 -0
  88. data/lib/ozdenui/web/comp/password-field.js +192 -0
  89. data/lib/ozdenui/web/comp/period-bar.js +436 -0
  90. data/lib/ozdenui/web/comp/phone-field.js +322 -0
  91. data/lib/ozdenui/web/comp/progress-bar.js +992 -0
  92. data/lib/ozdenui/web/comp/property-panel.js +3639 -0
  93. data/lib/ozdenui/web/comp/radio-button.js +527 -0
  94. data/lib/ozdenui/web/comp/range-slider.js +569 -0
  95. data/lib/ozdenui/web/comp/rich-text-editor.js +1064 -0
  96. data/lib/ozdenui/web/comp/scroll-area.js +308 -0
  97. data/lib/ozdenui/web/comp/scrolling-text.js +297 -0
  98. data/lib/ozdenui/web/comp/search-input/clear-round.svg +1 -0
  99. data/lib/ozdenui/web/comp/search-input/clear.svg +1 -0
  100. data/lib/ozdenui/web/comp/search-input/filter.png +0 -0
  101. data/lib/ozdenui/web/comp/search-input/filter.svg +1 -0
  102. data/lib/ozdenui/web/comp/search-input/search.svg +1 -0
  103. data/lib/ozdenui/web/comp/search-input.js +725 -0
  104. data/lib/ozdenui/web/comp/search-results.js +596 -0
  105. data/lib/ozdenui/web/comp/select-box.js +1862 -0
  106. data/lib/ozdenui/web/comp/settings-row.js +299 -0
  107. data/lib/ozdenui/web/comp/side-panel.js +616 -0
  108. data/lib/ozdenui/web/comp/slider-field.js +952 -0
  109. data/lib/ozdenui/web/comp/slider.js +838 -0
  110. data/lib/ozdenui/web/comp/smart-button/alert-black.png +0 -0
  111. data/lib/ozdenui/web/comp/smart-button/clock.png +0 -0
  112. data/lib/ozdenui/web/comp/smart-button.js +981 -0
  113. data/lib/ozdenui/web/comp/smart-table/clock.png +0 -0
  114. data/lib/ozdenui/web/comp/smart-table/down.png +0 -0
  115. data/lib/ozdenui/web/comp/smart-table/scroll.png +0 -0
  116. data/lib/ozdenui/web/comp/smart-table/sort.png +0 -0
  117. data/lib/ozdenui/web/comp/smart-table/up.png +0 -0
  118. data/lib/ozdenui/web/comp/smart-table.js +1883 -0
  119. data/lib/ozdenui/web/comp/sortable-list.js +1181 -0
  120. data/lib/ozdenui/web/comp/spark-line-box.js +738 -0
  121. data/lib/ozdenui/web/comp/splitter.js +411 -0
  122. data/lib/ozdenui/web/comp/status-bar.js +408 -0
  123. data/lib/ozdenui/web/comp/step-bar.js +345 -0
  124. data/lib/ozdenui/web/comp/stepper.js +753 -0
  125. data/lib/ozdenui/web/comp/tabs.js +1366 -0
  126. data/lib/ozdenui/web/comp/tag-input.js +1107 -0
  127. data/lib/ozdenui/web/comp/tap-effect.js +170 -0
  128. data/lib/ozdenui/web/comp/text-area-field.js +233 -0
  129. data/lib/ozdenui/web/comp/text-field.js +1006 -0
  130. data/lib/ozdenui/web/comp/time-line.js +398 -0
  131. data/lib/ozdenui/web/comp/time-picker.js +1032 -0
  132. data/lib/ozdenui/web/comp/tiny-select/arrow.svg +1 -0
  133. data/lib/ozdenui/web/comp/tiny-select.js +322 -0
  134. data/lib/ozdenui/web/comp/tiny-table.js +283 -0
  135. data/lib/ozdenui/web/comp/toast.js +891 -0
  136. data/lib/ozdenui/web/comp/toggle.js +757 -0
  137. data/lib/ozdenui/web/comp/tool-bar.js +760 -0
  138. data/lib/ozdenui/web/comp/tooltip.js +534 -0
  139. data/lib/ozdenui/web/comp/tree-view.js +1179 -0
  140. data/lib/ozdenui/web/comp/ui-effects.js +1097 -0
  141. data/lib/ozdenui/web/comp/ui-standards.js +403 -0
  142. data/lib/ozdenui/web/comp/url-field.js +190 -0
  143. data/lib/ozdenui/web/comp/web-view.js +588 -0
  144. data/lib/ozdenui/web/components.js +123 -0
  145. data/lib/ozdenui/web/index.html +39 -0
  146. data/lib/ozdenui/window.rb +188 -0
  147. data/lib/ozdenui/window_cocoa.rb +221 -0
  148. data/lib/ozdenui.rb +32 -0
  149. metadata +200 -0
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: a56c9462d0adea0a275d38ff0bbabd0100ad0d8e0f11fd5c6a8f6f632fcba7d8
4
+ data.tar.gz: 76222f9b1d8b71bfd5edaf06733ca6c55bdaa4c762d6674cc7b944583b78f9c1
5
+ SHA512:
6
+ metadata.gz: 6d04cce336e7a27c57c805f13a0bb16f1fbf8678145e6fe416c9b8b51016e3ec10bc2982f6574d1b926ad601759216bf0e6a35c96295d3813e1c982e884b5c17
7
+ data.tar.gz: e417667793c152d94c61aff1e888674c70f278bd8601d801e60e1377f214932c943188b473aa71617a14aa2575c4e87d84b07c7acc7db0c2c5e9ab7919199aa1
data/LICENSE ADDED
@@ -0,0 +1,14 @@
1
+
2
+ Copyright 2020-2026 Bugra Ozden <bugra.ozden@gmail.com> (https://bug7a.github.io/)
3
+
4
+ Licensed under the Apache License, Version 2.0 (the "License");
5
+ you may not use this file except in compliance with the License.
6
+ You may obtain a copy of the License at
7
+
8
+ http://www.apache.org/licenses/LICENSE-2.0
9
+
10
+ Unless required by applicable law or agreed to in writing, software
11
+ distributed under the License is distributed on an "AS IS" BASIS,
12
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ See the License for the specific language governing permissions and
14
+ limitations under the License.
data/NOTICE ADDED
@@ -0,0 +1,5 @@
1
+ OzdenUI (basic.js for Ruby)
2
+ Copyright 2020-2026 Bugra Ozden <bugra.ozden@gmail.com> (https://bug7a.github.io/)
3
+
4
+ This product includes software developed by Bugra Ozden
5
+ (https://bug7a.github.io/basic.js/).
data/README.md ADDED
@@ -0,0 +1,242 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="images/ozdenui-ruby-dark.svg">
4
+ <img src="images/ozdenui-ruby.svg" width="380" alt="OzdenUI for Ruby">
5
+ </picture>
6
+ </p>
7
+
8
+ # OzdenUI for Ruby
9
+
10
+ A small, modern window of its own in Ruby, made of [basic.js](https://bug7a.github.io/basic.js/) objects and the
11
+ components of the OzdenUI kit. Only Ruby: no JavaScript, no HTML, no CSS, no build step of a front end, **no other gem
12
+ and no compiler**. Your Ruby code makes the objects, and a window shows them.
13
+
14
+ <p align="center">
15
+ <img src="images/gallery.png" width="800" alt="The window of examples/gallery.rb: buttons, fields, choices, a list, a table, a chart and tabs of the OzdenUI kit">
16
+ </p>
17
+
18
+ The window above is [examples/gallery.rb](examples/gallery.rb), the main components of the kit in one window.
19
+
20
+ ```ruby
21
+ require "ozdenui"
22
+ include OzdenUI
23
+
24
+ @count = 0
25
+
26
+ def add(step)
27
+ @count += step
28
+ @label.text = @count.to_s
29
+ end
30
+
31
+ run(title: "Counter", width: 360, height: 260) do |page|
32
+ page.color = "#F4F5F7"
33
+ VGroup(gap: 16) do
34
+ @label = Label(text: "0", font_size: 48)
35
+ HGroup(hug: true, gap: 10) do
36
+ SmartButton(label_text: "Minus", on_click: -> { add(-1) })
37
+ SmartButton(label_text: "Plus", tone: "cyan", on_click: -> { add(1) })
38
+ end
39
+ end
40
+ end
41
+ ```
42
+
43
+ ```
44
+ gem install ozdenui
45
+ ruby counter.rb
46
+ ```
47
+
48
+ **[The site](https://bug7a.github.io/ozdenui-ruby/)** · **[The handbook](https://bug7a.github.io/ozdenui-ruby/handbook/)** (ten short chapters, English and Turkish; the files are in [handbook/](handbook/README.md))
49
+
50
+ v0.1, experimental: made and tested on macOS; Windows and Linux use the window of Edge or Chrome and are checked by
51
+ the tests of the repository, not yet by hand. Ruby 2.6 or newer.
52
+
53
+ - **macOS:** the window is the web view of the system (WKWebView), inside the program, made with `fiddle`, the
54
+ library of Ruby that calls the system. Nothing to install: it works with the Ruby that comes with macOS
55
+ (`/usr/bin/ruby`).
56
+ - **Windows, Linux:** the window is an app window of Edge or Chrome (no address bar, no tabs): nothing to install on
57
+ Windows, where Edge is always there.
58
+
59
+ **With an AI assistant** (Claude Code, Codex, Cursor, Copilot...): OzdenUI is new, so an assistant does not know it
60
+ yet. One command writes its rules (how a program is made, the layout, the events, the components, the mistakes to
61
+ avoid) into the folder of your project, where the assistant reads them by itself:
62
+
63
+ ```
64
+ ozdenui agents # into AGENTS.md
65
+ ozdenui agents CLAUDE.md # into another file
66
+ ```
67
+
68
+ And the assistant can look at the window it made, without a window:
69
+
70
+ ```
71
+ OZDENUI_LOOK=app.png ruby app.rb # runs the program as it is, saves a picture of its window, ends
72
+ ```
73
+
74
+ ## How it works
75
+
76
+ - The window shows a page of basic.js that is inside the gem, served only to this computer.
77
+ - An object in Ruby is a proxy: it keeps an id and the values it was given, and sends commands to the page, where the
78
+ real basic.js object lives. The events of the page come back as calls of your blocks.
79
+ - Everything of your program runs on one thread, one task at a time (the block of `run`, an event, a timer): no
80
+ locks. The commands of a task go to the page together, when the task ends.
81
+ - Reading a value the program gave, or the state a component tells (the text of a field, a checked box), asks nothing
82
+ of the page.
83
+
84
+ ## Objects
85
+
86
+ `include OzdenUI` gives the short names; without it they are methods of the module (`OzdenUI.Label(...)`,
87
+ `OzdenUI.run`). Five plain objects and two groups:
88
+
89
+ ```ruby
90
+ Box(20, 20, 200, 120, color: "white", round: 8) do # left, top, width, height
91
+ Label(12, 12, text: "In the box") # a place of its own in a Box
92
+ end
93
+ VGroup(gap: 12, padding: 20, align: "left top") do # one under the other
94
+ Label(text: "A name", font_size: 15)
95
+ Input(width: 220, placeholder: "Type here", on_enter: method(:save))
96
+ Button(text: "Save", on_click: method(:save))
97
+ Icon(width: 48, height: 48, picture: "photo.png")
98
+ end
99
+ ```
100
+
101
+ - The names are the names of basic.js and the kit, in snake_case: `fontSize` is `font_size:`, `onClick` is `on_click:`.
102
+ - A value that is not written keeps the default of basic.js. A size is a number (px) or a text (`"100%"`, `"auto"`).
103
+ `text:` is shown as it is written; `html:` takes HTML.
104
+ - A group is 100% x 100%; `hug: true` wraps its objects, `fill: true` takes the room the others leave.
105
+ - Later: `label.text = "Hi"`, `label.set(text: "Hi", font_size: 20)`, `label.text`, `obj.hide`, `obj.show`,
106
+ `obj.remove`, `box.add { ... }` to make more objects in a box.
107
+ - Events: `on_click:`, `on_input:`, `on_enter:`, `on_key_down:`..., or `obj.on(:dblclick) { |obj, event| ... }`; a
108
+ handler is a lambda, a method or a block that takes what it needs: `-> { }`, `->(obj) { }`, `->(obj, event) { }`.
109
+
110
+ ## Components
111
+
112
+ A component of the kit is a method of its name; its params are the params of the kit in snake_case.
113
+ `ozdenui doc SelectBox` prints them in the terminal, each with its default
114
+ ([all of them](lib/ozdenui/COMPONENTS.md)).
115
+
116
+ ```ruby
117
+ name = TextField(title_text: "Name", width: 260, on_enter: method(:save))
118
+ color = SelectBox(options: %w[Red Green Blue], value: "Green")
119
+ agree = CheckBox(label_text: "I agree", on_change: ->(box) { puts box.checked? })
120
+ SmartButton(label_text: "Save", tone: "cyan", on_click: lambda {
121
+ puts name.text, color.value, agree.checked? # read without a question to the page
122
+ })
123
+ ```
124
+
125
+ | For | Methods |
126
+ |---|---|
127
+ | Buttons | `SmartButton`, `ActionButton`, `HoldToConfirmButton` |
128
+ | Fields | `TextField`, `EmailField`, `PasswordField`, `NumberField`, `CurrencyField`, `PhoneField`, `UrlField`, `TextAreaField`, `SearchInput`, `TagInput` |
129
+ | Choices | `CheckBox`, `Toggle`, `RadioButton`, `SelectBox`, `TinySelect`, `Slider`, `SliderField`, `RangeSlider`, `Stepper`, `DatePicker`, `TimePicker`, `ColorPicker` |
130
+ | Lists and tables | `ItemList`, `SortableList`, `TreeView`, `SmartTable`, `DataTable`, `TinyTable` |
131
+ | Areas that hold objects | `ScrollArea`, `GridGroup`, `Tabs`, `Accordion`, `Splitter`, `SidePanel` |
132
+ | Bars | `MenuBar`, `ToolBar`, `StatusBar`, `ContextMenu`, `AppBar`, `BottomBar`, `Breadcrumbs` |
133
+ | Messages | `Tooltip`, `LoadingScreen`, `ProgressBar`, `LineProgressBar`, `StepBar`, `Notice`, `Badge` |
134
+ | Views | `GraphBox`, `MiniGraphBox`, `SparkLineBox`, `Gauge`, `LogView`, `ImageView`, `MarkdownView`, `JsonView`, `JsonEditor`, `CodeEditor`, `RichTextEditor`, `Canvas`, `ChatView`, `WebView`, `FilePicker`, `TimeLine` |
135
+
136
+ - A callback gets the object and the values the kit names: `on_select: ->(table, row) { puts row[:name] }`.
137
+ - A row of a table and an item of a list are Hashes: `{ key: "tr", text: "Türkiye" }`. Inside them the keys go to the
138
+ page as they are written, so a key of the kit is written as the kit writes it (`iconFile:`). What comes back from
139
+ the page is read with a text or a symbol: `row["name"]`, `row[:name]`.
140
+ - The areas: `ScrollArea(...) { ... }`, `GridGroup(columns: 3) { ... }`, `tabs.panel(key) { ... }`,
141
+ `accordion.section(key) { ... }`, `splitter.first { ... }` / `splitter.second { ... }`, `panel.body { ... }`.
142
+ - Later: `gauge.unit_text = "kg"` changes a param (with the method of the kit when it has one; the callback of the
143
+ component is not called by a change of the code); a method of the kit is a method of the object:
144
+ `list.add_item(key: "a", text: "A")`, and one that starts with `get_`, `is_` or `has_` returns its result
145
+ (`list.get_selected_keys`).
146
+ - A component is loaded into the page when the program first names it, with what it needs: a program pays only for
147
+ what it uses.
148
+ - Any component by its name: `component("Gauge", value: 72)`.
149
+
150
+ ## Dialogs and messages
151
+
152
+ ```ruby
153
+ delete_list if confirm("Delete the list?", danger: true) # waits; the window keeps working
154
+ name = prompt("The name of the list:") # nil: cancelled
155
+ alert("Saved.")
156
+ case ask("Save the changes?", "Save", "Don't save", "Cancel")
157
+ when "Save" then save
158
+ end
159
+ toast("Saved.") # never waits; type: :error, :warning, :info
160
+ path = open_file(types: %w[csv]) # the file dialog of the system
161
+ ```
162
+
163
+ ## Time and threads
164
+
165
+ ```ruby
166
+ timer = every(1000) { tick } # again and again; timer.stop ends it
167
+ after(3000) { close } # once
168
+
169
+ Thread.new do # a slow job: the window does not wait for it
170
+ text = download
171
+ ui { @label.text = text } # the objects are changed on the thread of the window
172
+ end
173
+ ```
174
+
175
+ An object changed from another thread raises with this fix in its message; nothing breaks without a word.
176
+
177
+ ## Light, dark, minimal
178
+
179
+ ```ruby
180
+ run(theme: "dark") { ... } # "light", "dark", "auto"
181
+ run(style: "minimal", accent: "#2A78D6") { ... } # small, made of lines, one color
182
+ ```
183
+
184
+ `run(language: "tr")` is the language of the texts of the window (capital letters, word breaks).
185
+
186
+ In a dark window every component takes its dark look by itself, and the plain objects and the page are dark too.
187
+ `set_theme("dark")` changes it while the program runs (the block of `run` runs again). One component:
188
+ `style_name: "..."` (`ozdenui doc` names its packages) or `style: { box: { round: 12 } }`.
189
+
190
+ ## Examples
191
+
192
+ `ruby -Ilib examples/gallery.rb` (from a clone of the repository):
193
+
194
+ | | |
195
+ |---|---|
196
+ | `counter`, `greeting`, `basics` | the first steps |
197
+ | `notes`, `todo`, `form`, `settings`, `calculator` | small programs |
198
+ | `dialogs`, `charts`, `clock`, `game` | dialogs, charts, timers, a Box with places and keys |
199
+ | `csv_viewer`, `json_viewer`, `image_viewer`, `editor`, `markdown_editor` | files of the computer |
200
+ | `job_log` | a thread that tells its progress |
201
+ | `chat`, `gallery`, `minimal_theme` | the bigger ones |
202
+
203
+ ## Limits of v0.1
204
+
205
+ - macOS is the tested system. Windows and Linux open the app window of Edge or Chrome (with none of them: a tab of
206
+ the default browser); the web view of the system there is a later step.
207
+ - On macOS the menu bar names the program by the title of its window, but the Dock shows it as a Ruby program (it is
208
+ not an app bundle).
209
+ - One window for a program.
210
+ - A callback of the kit that must answer at once (a validator, `createItemView`) can not be a block of the program:
211
+ the answer of the program comes after the page has drawn.
212
+ - A file dropped on a `FilePicker` gives its name, not its path on the computer; a click on it opens the file dialog
213
+ of the system, and those files have their paths (`picker.paths`).
214
+ - With Bundler on Ruby 3.5 or newer, add `gem "fiddle"` to the Gemfile (it left the default gems); without it the
215
+ window of macOS is the window of a browser.
216
+ - No hot reload: `ruby app.rb` again.
217
+
218
+ ## Development
219
+
220
+ ```
221
+ ruby test/ozdenui_test.rb # the checks; test_window plays a real page in a hidden Chrome
222
+ checks/look-all.sh # a picture of every example, light and dark (pictures/)
223
+ ./update-web.sh --commit HEAD # the kit copy (lib/ozdenui/web) from the js-components repository, then kit.json
224
+ ruby tools/gen.rb # kit.json and COMPONENTS.md again, after a change of tools/spec.json
225
+ gem build ozdenui.gemspec
226
+ ```
227
+
228
+ `lib/ozdenui/kit.json` (the table of the components) and `lib/ozdenui/COMPONENTS.md` are written by `tools/gen.rb`
229
+ from the files of the kit in `lib/ozdenui/web/comp` and from `tools/spec.json`; never edit them by hand, and never
230
+ edit the copy in `lib/ozdenui/web/basic` and `lib/ozdenui/web/comp`.
231
+
232
+ The family: [OzdenUI for Python](https://github.com/bug7a/ozdenui-python) and
233
+ [OzdenUI for Go](https://github.com/bug7a/ozdenui-go) are the same kit for Python and Go;
234
+ [basic.js](https://bug7a.github.io/basic.js/) and the [components](https://bug7a.github.io/js-components/) are the
235
+ JavaScript they stand on.
236
+
237
+ ## License
238
+
239
+ Apache 2.0. Copyright 2026 Buğra Özden. basic.js and the components of the kit are in `lib/ozdenui/web/` (Apache 2.0,
240
+ the same author).
241
+
242
+ Developed with the help of Claude Code (Anthropic).
data/exe/ozdenui ADDED
@@ -0,0 +1,17 @@
1
+ #!/usr/bin/env ruby
2
+ # Bismillah
3
+ #
4
+ # ozdenui - ozdenui v0.1 (OzdenUI: basic.js for Ruby)
5
+ # The command of the gem: the rules of OzdenUI for the AI assistant of a project (agents), and the params of a
6
+ # component in the terminal (doc).
7
+ #
8
+ # Started Date: November 2026
9
+ # Webpage: https://bug7a.github.io/ozdenui-ruby/
10
+ #
11
+ # Copyright 2026 Bugra Ozden <bugra.ozden@gmail.com> (https://bug7a.github.io/)
12
+ # Licensed under the Apache License, Version 2.0
13
+ # SPDX-License-Identifier: Apache-2.0
14
+
15
+ require_relative "../lib/ozdenui/command"
16
+
17
+ exit OzdenUICommand.run(ARGV)
@@ -0,0 +1,210 @@
1
+ # OzdenUI for Ruby: rules for an AI assistant
2
+
3
+ This project uses **OzdenUI** (`gem install ozdenui`): desktop windows written in plain Ruby. It is a new library, so
4
+ do not guess from Shoes, Tk, Glimmer, GTK or a web framework: there is no widget tree to build, no layout manager
5
+ object, no HTML, no CSS file and no JavaScript to write. Everything below is the whole way of working.
6
+
7
+ ## Where the truth is
8
+
9
+ - **The params of a component:** `ozdenui doc SelectBox` in a terminal (every param with its default and what it
10
+ takes, its looks, the values it gives back, its methods). Read it before you use a component for the first time.
11
+ `ozdenui doc` lists every component.
12
+ - **Example programs:** https://github.com/bug7a/ozdenui-ruby/tree/main/examples (`gallery.rb` shows the main components).
13
+
14
+ ## A program
15
+
16
+ ```ruby
17
+ require "ozdenui"
18
+ include OzdenUI
19
+
20
+ PAGE_COLOR = "#F4F5F7"
21
+
22
+ @notes = [] # the data of the program is plain Ruby
23
+
24
+ def add_note
25
+ typed = @name.text.strip # the state is in the program: reading asks nothing of the window
26
+ if typed.empty?
27
+ toast("Write a note first.", type: :warning)
28
+ return
29
+ end
30
+ @notes << typed
31
+ @list.add { Label(text: typed, font_size: 15) } # objects made later go into a box the same way
32
+ @empty.hide
33
+ @name.value = ""
34
+ @count.text = "Notes: #{@notes.length}"
35
+ end
36
+
37
+ # Once, at the end of the program. The block runs when the window is ready: make the objects here.
38
+ run(title: "Notes", width: 480, height: 420) do |page|
39
+ page.color = PAGE_COLOR
40
+ VGroup(gap: 0) do # a group is as large as its box: here the whole window
41
+ HGroup(height: 60, padding: [16, 0], gap: 10, align: "left center", color: "white") do
42
+ @name = TextField(placeholder: "A new note", width: 260, on_enter: method(:add_note))
43
+ SmartButton(label_text: "Add", tone: "cyan", on_click: method(:add_note))
44
+ end
45
+ @list = ScrollArea(padding: 16, gap: 10, align: "left top") do # takes the room that is left
46
+ @empty = Label(text: "No notes yet", font_size: 15)
47
+ end
48
+ @count = Label(text: "Notes: 0", font_size: 13, height: 28)
49
+ end
50
+ end
51
+ ```
52
+
53
+ - `include OzdenUI` gives the short names (`Label(...)`, `run`, `toast`); without it every name is
54
+ `OzdenUI.Label(...)`, `OzdenUI.run`. An object maker starts with a capital letter: `Label(text: "x")`,
55
+ `VGroup(gap: 8) do ... end`, `VGroup do ... end`. Alone, with no value and no block, it needs its brackets: `Box()`.
56
+ - `run(title:, width:, height:, theme: "light" | "dark" | "auto", style: "minimal", accent: "#2A78D6")`; `width` and
57
+ `height` are the size of the page. `close`, `set_title("...")`, `theme`, `dark?`. `language: "tr"` when the texts of
58
+ the window are not English (the capital letters of Turkish: "İ").
59
+ - Objects are made in the block of `run` or later (an event, a timer), never before `run`. `run` returns when the
60
+ window is closed.
61
+ - Keep the objects the program changes later in variables: `@name` (an instance variable is seen by the block and by
62
+ the methods of the file) or a local variable the lambdas see. In a bigger program: a class of your own, with
63
+ `OzdenUI.run { App.new.start }`.
64
+
65
+ ## Objects and values
66
+
67
+ - Five plain objects: `Box`, `Label`, `Button`, `Input`, `Icon`. The rest are components (below): `CheckBox(...)`.
68
+ - **The names are the names of basic.js and the kit, in snake_case:** `fontSize` is `font_size:`, `labelText` is
69
+ `label_text:`, `onClick` is `on_click:`. A value is a named value when the object is made and a setter later:
70
+ `label.text = "Hi"`, `label.font_size = 20`, or more at once: `label.set(text: "Hi", font_size: 20)`.
71
+ - Reading: `label.text`, `field.text`, `select_box.value`, `box.checked?`, `list.selected_keys`:
72
+ what the program gave, or what the window told. A value that was never given is `nil`.
73
+ - Every object: `color:` (the background), `border:`, `border_color:`, `round:`, `opacity:`, `visible:`, `width:`,
74
+ `height:`, `css: { letterSpacing: "1px" }`. A size is a number (px) or a text: `"100%"`, `"auto"`. Flags take
75
+ `true` / `false`.
76
+ - A value that is not written keeps the default of the kit; `nil` is "not written" (`""` is an empty text, written).
77
+ - `text:` is shown exactly as written (a `<b>` stays `<b>`); HTML goes in as `html:`.
78
+ - `obj.remove` removes it for good; to hide it for a while: `obj.hide`, `obj.show`.
79
+ - **Inside a table or a list (an item, a row, a column) the keys go to the window as they are written:** write them as
80
+ the kit does (`{ key: "tr", text: "Türkiye", iconFile: "tr.png" }`), and the keys of your own rows as you like. Only
81
+ the keys of a look (`style:`, `css:`) may be snake_case.
82
+
83
+ ## Layout
84
+
85
+ - **Only a `Box`, a group and the areas of some components hold objects**: the objects made inside their block go
86
+ into them. Later: `box.add { ... }`.
87
+ - `VGroup` (one under the other), `HGroup` (side by side), `GridGroup(columns: 4)`: `gap:`, `padding:` (`20` or
88
+ `[x, y]`), `align:` (`"center"` is the default; `"left top"`, `"right center"`...), `wrap: true`.
89
+ - **A group is `width: "100%"`, `height: "100%"` by default.** A group inside another one almost always needs one
90
+ of: `hug: true` (as large as its objects), `height: "auto"` / a number, or `fill: true` (the room the others leave:
91
+ the height in a `VGroup`, the width in an `HGroup`). Two groups of 100% in one `VGroup` squeeze each other.
92
+ - A typical window: `VGroup(gap: 0) do ... end` holding a bar of a fixed height, a middle part with `fill: true` (or a
93
+ `ScrollArea`, which takes the room by itself and scrolls), a line at the bottom.
94
+ - The block of a group gets the group: `GridGroup(columns: 4) { |grid| wide = SmartButton(...); grid.place(wide, column_span: 2) }`.
95
+ - In a group an object needs only its size. In a `Box` or on the page it has a place: `Box(20, 20, 200, 120, color: "white")`
96
+ (left, top, width, height) or `left:`, `top:` (for a game or a drawing).
97
+
98
+ ## Events
99
+
100
+ - `on_click: -> { ... }` or `on_click: method(:save)` when the object is made, `obj.on_click = -> { ... }` later,
101
+ `obj.on(:key_down) { |obj, event| ... }` for one more handler (it returns a lambda that removes it). The page
102
+ listens to the window: `page.on(:key_down) { |_page, event| ... }`, `page.on(:resize) { ... }`.
103
+ - A handler takes what it needs: `-> { }`, `->(obj) { }` or `->(obj, event) { }` (`event.key`, `event.x`, `event.y`,
104
+ `event.shift`...).
105
+ - A component tells a change with a callback param: `on_change: ->(box) { puts box.checked? }`. The values after the
106
+ object are the ones the kit names (`ozdenui doc`): `on_select: ->(table, row) { }`. **A change made by the code does
107
+ not call it**, only the user's does.
108
+ - Everything runs one at a time on one thread, so no locks; but a slow block freezes the window. Never `sleep` in an
109
+ event: `after(ms) { ... }` once, `every(ms) { ... }` again and again (both return a timer: `timer.stop`). A slow job
110
+ (a download, a big file, an AI call) runs in a thread of its own and changes the objects only inside `ui { ... }`:
111
+
112
+ ```ruby
113
+ Thread.new do
114
+ text = download # the window does not wait
115
+ ui { @label.text = text } # back on the thread of the window
116
+ end
117
+ ```
118
+
119
+ ## Components
120
+
121
+ Each is a method of its name; its state is read from the program (`field.text`, `select_box.value`, `box.checked?`,
122
+ `list.selected_keys`: `ozdenui doc` names them).
123
+
124
+ | For | Methods |
125
+ |---|---|
126
+ | Buttons | `SmartButton` (`label_text:`, `tone: "cyan"` main / `"orange"` delete / `"accent"`, `on_click:`) |
127
+ | Fields | `TextField`, `EmailField`, `PasswordField`, `NumberField`, `CurrencyField`, `PhoneField`, `UrlField`, `TextAreaField`, `SearchInput`, `TagInput` (`title_text:`, `placeholder:`, `value:`, `on_enter:`, `on_change:`) |
128
+ | Choices | `CheckBox`, `Toggle`, `RadioButton`, `SelectBox` (`options:`, `value:`), `Slider`, `SliderField`, `RangeSlider` (`low_value:`, `high_value:`; read `obj.low`, `obj.high`), `Stepper`, `DatePicker` (`date:`), `TimePicker` (`time:`), `ColorPicker` (`selected_color:`); the others give `obj.value` |
129
+ | Lists and tables | `ItemList` (`items:`), `SortableList`, `TreeView`, `SmartTable` (`title_data_list:`, `item_data_list:`: very many rows), `DataTable` |
130
+ | Areas that hold objects | `ScrollArea`, `GridGroup` (with a block), `Tabs` (`tabs.panel(key) { ... }`), `Accordion` (`acc.section(key) { ... }`), `Splitter` (`split.first { ... }`, `split.second { ... }`), `SidePanel` (`panel.body { ... }`) |
131
+ | Bars | `MenuBar`, `ToolBar`, `StatusBar`, `ContextMenu` |
132
+ | Messages | `alert`, `confirm`, `prompt`, `ask`, `toast`, `Tooltip`, `LoadingScreen`, `ProgressBar`, `StepBar` |
133
+ | Views | `GraphBox` (charts), `LogView`, `ImageView`, `MarkdownView`, `JsonView`, `JsonEditor`, `CodeEditor`, `Canvas`, `ChatView`, `WebView`, `FilePicker`, `Gauge` |
134
+
135
+ - A dialog returns its answer, like a question in a terminal: `if confirm("Delete it?", danger: true)`,
136
+ `name = prompt("Name:")` (`nil`: cancelled), `alert("Saved.")`, `ask("Save?", "Save", "Don't save", "Cancel")` (the
137
+ text of the pressed button, `nil`: closed). The window keeps working while the code waits.
138
+ - `toast("Saved.")` never waits; `type: :success` (default), `:error`, `:warning`, `:info`; `title:`.
139
+ - The file dialogs of the system: `open_file`, `open_files`, `save_file`, `choose_folder` return a real path or `nil`
140
+ (`open_files`: a list); `open_file(title:, directory:, types: %w[png jpg])`, `save_file(file_name: "notes.txt")`.
141
+ A click on a `FilePicker` opens that dialog too: `picker.paths` are the chosen files (a dropped file has no path).
142
+ - A picture (`Icon(picture: "photo.png")`, a param whose name ends with `_file`: `icon_file:`, `image_file:`) takes a
143
+ path of this computer; in another place (an item of a list): `picture("photo.png")`, also of the text of an SVG or
144
+ of bytes (`File.binread`).
145
+ - A param of the kit changes later with its setter (`gauge.unit_text = "kg"`); a method of the kit is a method of the
146
+ object in snake_case: `list.add_item(key: "a", text: "A")` (not waited for); one that starts with `get_`, `is_` or
147
+ `has_` returns its result (`list.get_selected_keys`: a question to the window, not in a loop). Any method:
148
+ `obj.call(:method_name, values)`, `obj.ask(:method_name)`. What each takes is in its file of the kit:
149
+ https://github.com/bug7a/ozdenui-ruby/tree/main/lib/ozdenui/web/comp
150
+ - What comes from the window (a row in a callback, the result of `ask`): a table is a Hash read with a text or a
151
+ symbol (`row["name"]`, `row[:name]`), a flag of the kit is `1` / `0`, not `true` / `false`: `on?(value)` reads it.
152
+ - A big or fast value is asked, not kept: the text of a `CodeEditor` (`editor.get_value`), the value of a
153
+ `JsonEditor`, the selected row of a `SmartTable` (`table.measure(:selected_item_data)`).
154
+ - The columns of a `SmartTable`: `title_data_list: [{ name: "NAME", dataTitle: "name", dataType: "string", width: 160,
155
+ sortable: 1 }]`; its rows: `item_data_list: rows` (Hashes), later `table.item_data_list = rows`.
156
+ - Small helpers: `field.valid?` (shows the warning of a field, true when its text is right), `radio_value(group)` (the
157
+ `value:` of the checked `RadioButton`), `show_hint(obj, "Copied", 1500)` (a bubble for a while),
158
+ `log_view.writer(:info)` (an output like `$stdout`, from any thread), `obj.style_name = "dark"` (the look of one bar,
159
+ editor or view while the program runs), `obj.measure(:width)` (a value as the window has it now).
160
+ - A picture given to a method is an address: `view.set_image(picture(path))`.
161
+ - A number a component writes (`format_value:` of a `GraphBox`, `value_format:` of a `Stepper`) takes a text like
162
+ `"{:,.2f} TL"` (1,234.50 TL), `"{:.0f} kg"`, `"{:.1%}"`: not a block.
163
+ - A method of the kit named like a method every Ruby object has (`send` of a `ChatView`, `display`, `method`) is
164
+ called with `obj.call(:send, text)`. Do not name your own top-level methods like the ones of Ruby (`send`, `format`,
165
+ `display`, `open`, `test`) or of OzdenUI (`run`, `close`, `ask`, `page`, `after`).
166
+ - An icon may be the text of an SVG: `icon_file: picture(svg_text)`.
167
+ - A name of the kit that is not snake_case goes as a text: `LoginPage("tab_border" => 1)`. Any component by its name:
168
+ `component("Gauge", value: 72)`.
169
+
170
+ ## Looks
171
+
172
+ - `run(theme: "dark")`: every component takes its dark look by itself. For your own colors:
173
+ `text_color = dark? ? "#9AA3B5" : "#5A6270"`.
174
+ - `run(style: "minimal", accent: "#2A78D6")`: a small look made of lines, in one color; the main button is
175
+ `tone: "accent"`.
176
+ - `set_theme("dark")` changes the theme while the program runs: the page is made again and the block of `run` runs
177
+ again, so every object is new and the timers set before are gone. Keep the data in variables outside the block,
178
+ fill the objects from them in the block, and set the timers there.
179
+ - One component: `style_name: "..."` (`ozdenui doc` names its packages), or `style: { box: { color: "#FFF" } }`;
180
+ `unframed: true`: no border and no rounded corners (a table or an editor that fills the room between two bars).
181
+ - Keep the colors of a program as constants at the top of its file.
182
+
183
+ ## Mistakes to avoid
184
+
185
+ 1. A nested group without `hug: true`, `fill: true` or a height (see Layout).
186
+ 2. Changing an object from a thread of your own: it raises with the fix (`ui { ... }`).
187
+ 3. Waiting in an event (`sleep`, a download): the window freezes.
188
+ 4. Reading a value that was never given (`label.width` of an `"auto"` label) is `nil`: `obj.measure(:width)` asks the
189
+ window. Keep `measure` and the `get_...` methods out of loops.
190
+ 5. Putting an object into a `Label` or a button. Make it next to it, in the same box.
191
+ 6. A name that does not exist. The terminal says it with the line of the program
192
+ (`ozdenui: app.rb:12: Label: font_szie is not a value of Label (did you mean font_size?)`): run the program and
193
+ **read the terminal**. An error in a block is told there too (`ozdenui: a task failed: ...`); the window stays open.
194
+ 7. A kit name in snake_case inside an item or a column (`icon_file:` in an item of a list): there it is `iconFile:`.
195
+ 8. Colors written for a light window only, in a program that may open dark.
196
+ 9. A callback that must answer at once (a validator that returns `false`) can not be a block of the program.
197
+ 10. Saying a window is right without a look at it (below).
198
+
199
+ ## Running and checking
200
+
201
+ - **Look at the window you made:** `OZDENUI_LOOK=app.png ruby app.rb` runs the program as it is, saves a picture of
202
+ its window as `app.png` and ends. Read the picture: a program that runs without an error can still have a part
203
+ covered, cut or squeezed. `OZDENUI_THEME=dark OZDENUI_LOOK=dark.png OZDENUI_LOOK_WAIT=3 ruby app.rb`: the dark
204
+ window, more seconds before the picture. (It needs Chrome, Edge or Chromium on the computer; no window opens.)
205
+ - `ruby app.rb` opens a real window and returns when it is closed. To check a program without a person, close it from
206
+ the code: `after(3000) { close }` as the first line of the block of `run`, then read the terminal.
207
+ - A check that plays the program from code must not reach a dialog: it waits for a person.
208
+ - `run(debug: true)` gives the developer tools of the web view (right click > Inspect Element).
209
+ - macOS: the window is the web view of the system. Windows and Linux: the app window of Edge or Chrome. The gem needs
210
+ no other gem and no compiler; Ruby 2.6 or newer (also the Ruby that comes with macOS).