From bcc2d10e564dff466030bdd59f7530fc035eb281 Mon Sep 17 00:00:00 2001
From: Marek Piasecki <mad@maniak.pro>
Date: Tue, 17 Jan 2023 21:14:02 +0100
Subject: [PATCH] writing documentation in progress

---
 src/index.js                |   3 +-
 src/main.imba               | 137 +++++++++-------------------------
 src/router.imba             |   3 +-
 src/router_tag.imba         |   6 +-
 src/views.json              |   1 +
 src/views/home.imba         |  18 +++++
 src/views/installation.imba |  30 ++++++++
 src/views/usage.imba        | 144 ++++++++++++++++++++++++++++++++++++
 8 files changed, 232 insertions(+), 110 deletions(-)
 create mode 100644 src/views.json
 create mode 100644 src/views/home.imba
 create mode 100644 src/views/installation.imba
 create mode 100644 src/views/usage.imba

diff --git a/src/index.js b/src/index.js
index f72e144..737b6bb 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,3 +1,2 @@
 import './router.imba'
-import './main.imba'
-R.url_changed() // the best if you move it right before imba.mount
\ No newline at end of file
+import './main.imba'
\ No newline at end of file
diff --git a/src/main.imba b/src/main.imba
index 104c1e4..2db5eba 100644
--- a/src/main.imba
+++ b/src/main.imba
@@ -1,13 +1,16 @@
-css
+global css
 	html, body m:0 p:0
 	body ff:mono bgc:gray9
 	a c:violet6 td:none td@hover:underline
-	.active, .activated filter:brightness(130%)
+	.active filter:brightness(130%)
+	.activated bgc:violet3
+	.disabled, .disabled@hover filter:grayscale(100%)
+	.zoomed scale:1.05
 	.button d:inline-block m:2px bgc:none c:violet7 td:none bxs:sm us:none
-	.button@hover, .button.active bxs:md filter:hue-rotate(5deg) ml:0px pl:12px td:none
+	.button@hover, .button.active bxs:md filter:hue-rotate(5deg) mb:0px pt:12px td:none
 	.button, code, .bordered p:10px bd:2px solid violet5 rd:10px d:inline-block
 	.bordered p:2.5px bw:1.5px c:violet9
-	.night filter:invert(100%)
+	.night filter:invert(20%)
 	.gradient
 		bg:linear-gradient(to right,violet7,blue6,violet7)
 		fw:normal
@@ -19,12 +22,12 @@ tag App
 		d:bbox mx:auto my:50px bgc:white p:40px rd:5px maw:1024px of:auto
 		@lt-xs m:0 px:0 rd:0
 
-	<self.night=R.param('night')>
+	<self.night=R.param('night') .zoomed=R.param('zoomed')>
 		<param-preview>
 		<h2.gradient> "pro-router-imba2: Imba2 integration with pro-router"
 		<[d:flex flw:wrap w:100% jc:space-between]>
-			<Menu>
-			<pro-router[mx:40px maw:750px]>
+			<app-menu>
+			<pro-router[mx:40px]>
 		###
 		<pro-ref view="b" params={ project: 2}> "b/project/2"
 		<pro-ref-f view="c" params={ book: 3}> "c/book/3"
@@ -32,104 +35,26 @@ tag App
 		<input$v type='text' value=R.param('e') @keyup=R.write('e', $v.value)>
 		###
 
-tag Menu
-	<self[d:flex fld:column mx:auto mb: 50px]>
+tag app-menu
+	<self[d:flex fld:row flw@lt-xs:wrap mx:auto mb: 50px jc:center]>
 		<pro-ref.button view=v> v.toUpperCase! for v in R.views
-		###
-		<pro-ref.button view="foo"> 'WRONG WAY!'
-		<pro-toggle.button param="night">
-			<label> "NIGHT"
-			<input type='checkbox' checked=R.param('night')>
-		###
 
 tag param-preview
 	<self> "{R.view}: {JSON.stringify(R.params).replace(/"/g, ' ')}"
 
-extend tag view-home
-	<self>
-		"What is "
-		<b> "pro-router"
-		" you can see here: "
-		<a href="http://router.maniak.pro"> "router.maniak.pro"
-		<br>
-		"What is "
-		<a href="https://imba.io"> "imba"
-		" you surely know."
-		<br>
-		"This package integrates both."
-		<br>
-		<br>
-		"Go to your project directory and run:"
-		<br>
-		<br>
-		<code> "npm install pro-router-imba2 --save"
-
-tag view-installation
-	<self>
-		"For your convenience package provides "
-		<b> "vite plugin"
-		" and installation command"
-		"."
-		<br>
-		"Vite plugin will automatically define views for the router. Thanks to pro-router paradigm you will not write route definitions at all."
-		<br>
-		<br>
-		"1. Create imba project (or go to directory of an existing one):"
-		<br>
-		<pre><code>
-			"""
-			npx imba create my-app
-			cd my-app
-			npm install
-			"""
-		<br>
-		"2. Install pro-router-imba2 and run development server:"
-		<pre><code>
-			"""
-			npm install pro-router-imba2 --save
-			npx pro-router init
-			npm run dev
-			"""
-		<br>
-		"3. Add "
-		<.bordered> "<pro-router>"
-		" component to your app (in "
-		<.bordered> "src/main.imba"
-		" file)."
-		<br>
-		"The simplest application would look like this:"
-		<imba-code file='src/main.imba'>
-			"""
-			imba{<c-op> '.'}mount {<c-tag> 'pro-router'}
-			"""
-		<br>
-		"A bit more complex example:"
-		<imba-code>
-			"""
-			{<c-tag-def> 'my-app'}
-			    {<c-tag> 'self'}
-			        {<c-tag> "pro-ref{<c-el> ' view'}{<c-op> '='}{<c-el> 'v'}"} {<c-op> 'for'} v {<c-op> 'in'} {<c-c> 'R'}{<c-op> '.'}views {<c-com> 'render menu'} 
-			        {<c-tag> "pro-router"}                      {<c-com> 'slot for current view'}
-
-			{<c-tag-def> 'view-home'}
-			    {<c-tag> 'self'} 'Hello World!'
-
-			{<c-tag-def> 'view-another-view'}
-			    {<c-tag> 'self'} 'This is another view.'
-
-			imba{<c-op> '.'}mount {<c-tag> 'my-app'}
-			"""
-		<br>
-		"4. Everything is already set."
-
 tag imba-code < pre
 	prop file
-	css bgc:gray8 d:block
-		code bd:0 rd:0 
-			&.file bgc:amber3 d:block
+	prop url
+	css 
+		code d:block bd:0 rd:0 bgc:gray8
+			&.file bgc:amber3
 			&.content c:gray3
-	<self>
+			&.url bgc:gray3
+				.url bgc:white c:gray7 rd:full p:4px
+	<self[bgc:gray1 bd:1.1px solid gray3 fs:larger]>
 		<code.file> file if file
+		<code.url><.url> url if url
+		<slot name='live'>
 		<code.content><slot>
 
 tag c-el
@@ -143,12 +68,10 @@ tag c-com < c-el
 	<self>
 		"# "
 		<slot>
-###
-tag c-class < c-el
-	<self[c:amber4]>
-		<c-dot>
-		<slot>
-###
+tag c-str < c-el
+	<self> "'{<[c:amber6 d:inline]><slot>}'"
+global css .c-br c:amber4 d:inline
+
 tag c-tag < c-el
 	<self[c:white]>
 		"<"
@@ -160,8 +83,14 @@ tag c-tag-def < c-el
 		"tag "
 		<[c:green5 d:inline]><slot>
 
-tag view-usage
-	<self> "List of components"
+tag pro-tip
+	<self[bgc:gray0 p:15px]>
+		<[c:violet7 fw:bold txs:amber4 bdb:1.5px solid violet4]> "PRO TIP: "
+		<slot>
+
+import './views/home.imba'
+import './views/installation.imba'
+import './views/usage.imba'
 
 tag view-examples
 	<self> "Examples:"
diff --git a/src/router.imba b/src/router.imba
index 07dd1b6..e3fb596 100644
--- a/src/router.imba
+++ b/src/router.imba
@@ -1,8 +1,9 @@
 import "pro-router/standalone" # standalone operates on "/#/" hash style url; for regular "/" url use: "pro-router/router"
 import "./router_tag.imba"
+import views from "./views.json"
 import { helpers } from "./helpers.imba"
 
-R.init helpers: helpers, root: 'home', render: imba.commit
+R.init helpers: helpers, views: views, root: 'home', render: imba.commit
 
 tag view-home
 	<self><h1> 'Imba2 on Pro Router is working...'
diff --git a/src/router_tag.imba b/src/router_tag.imba
index fa655cf..e8d40bc 100644
--- a/src/router_tag.imba
+++ b/src/router_tag.imba
@@ -13,7 +13,7 @@ tag pro-toggle
 
 tag pro-ref-f < a # f - forget current params in new destination
 	prop view
-	prop params = {}
+	prop params
 	prop go
 
 	def render
@@ -25,6 +25,6 @@ tag pro-ref-f < a # f - forget current params in new destination
 
 tag pro-ref < pro-ref-f
 	get url
-		#params = JSON.parse JSON.stringify(params) # duplicate object
-		#params[k] ||= v for own k, v of R.safe_params
+		#params = params ? JSON.parse JSON.stringify(params) : {} # duplicate object
+		#params[k] ??= v for own k, v of R.safe_params
 		R.to_path view, #params
\ No newline at end of file
diff --git a/src/views.json b/src/views.json
new file mode 100644
index 0000000..4af5974
--- /dev/null
+++ b/src/views.json
@@ -0,0 +1 @@
+["home","examples","why-to-use-it","installation","usage"]
\ No newline at end of file
diff --git a/src/views/home.imba b/src/views/home.imba
new file mode 100644
index 0000000..d97e448
--- /dev/null
+++ b/src/views/home.imba
@@ -0,0 +1,18 @@
+extend tag view-home
+	<self>
+		"What is "
+		<b> "pro-router"
+		" you can see here: "
+		<a href="http://router.maniak.pro"> "router.maniak.pro"
+		<br>
+		"What is "
+		<a href="https://imba.io"> "imba"
+		" you surely know."
+		<br>
+		"This package integrates both."
+		<br>
+		<br>
+		"Go to your project directory and run:"
+		<br>
+		<br>
+		<code> "npm install pro-router-imba2 --save"
\ No newline at end of file
diff --git a/src/views/installation.imba b/src/views/installation.imba
new file mode 100644
index 0000000..b7227d3
--- /dev/null
+++ b/src/views/installation.imba
@@ -0,0 +1,30 @@
+tag view-installation
+	<self>
+		"For your convenience package provides "
+		<b> "vite plugin"
+		" and installation command"
+		"."
+		<br>
+		"Vite plugin will automatically define views for the router. Thanks to pro-router paradigm you will not write route definitions at all."
+		<br>
+		<br>
+		"1. Create imba project (or go to directory of an existing one):"
+		<br>
+		<pre><code>
+			"""
+			npx imba create my-app
+			cd my-app
+			npm install
+			"""
+		<br>
+		"2. Install pro-router-imba2 and run development server:"
+		<pre><code>
+			"""
+			npm install pro-router-imba2 --save
+			npx pro-router init
+			npm run dev
+			"""
+		<br>
+		"3. "
+		<b> "There is no three. "
+		"Everything is already set."
diff --git a/src/views/usage.imba b/src/views/usage.imba
new file mode 100644
index 0000000..a9ee512
--- /dev/null
+++ b/src/views/usage.imba
@@ -0,0 +1,144 @@
+tag view-usage
+	<self>
+		"This integration provides "
+		<b> 3
+		" components:"
+		<br>
+		<br>
+		<.bordered> "<pro-ref>"
+		" generates a link with a proper address hooked to the router."
+		<br>
+		<br>
+		<b> "Examples:"
+		<br>
+		<imba-code url="/tips/about/usage/_local_value/1">
+			<c-el>
+				<c-tag> "pro-ref{<c-el> " go{<c-op> '='}{<c-str> '/exact/url'}"}"
+				" "
+				<c-com> "<a href=\"/exact/url\">"
+			<br>
+			<br>
+			<c-el>
+				<c-tag> "pro-ref{<c-el> " view{<c-op> '='}{<c-str> 'docs'}"}"
+				" "
+				<c-com> "<a href=\"/docs/about/usage\">"
+			<br>
+			<c-el>
+				<c-tag> "pro-ref-f{<c-el> " view{<c-op> '='}{<c-str> 'docs'}"}"
+				" "
+				<c-com> "<a href=\"/docs\">"
+			<br>
+			<br>
+			<c-el>
+				<c-tag> "pro-ref{<c-el> " view{<c-op> '='}{<c-str> 'docs'} params{<c-op> '='}{<.c-br> '{'} chapter{<c-op> ':'} {<c-c> 1}{<.c-br> '}'}"}"
+				" "
+				<c-com> "<a href=\"/docs/about/usage/chapter/1\">"
+			<br>
+			<c-el>
+				<c-tag> "pro-ref-f{<c-el> " view{<c-op> '='}{<c-str> 'docs'} params{<c-op> '='}{<.c-br> '{'} chapter{<c-op> ':'} {<c-c> 1}{<.c-br> '}'}"}"
+				" "
+				<c-com> "<a href=\"/docs/chapter/1\">"
+			<br>
+			<br>
+			<c-el>
+				<c-tag> "pro-ref{<c-el> " params{<c-op> '='}{<.c-br> '{'} chapter{<c-op> ':'} {<c-c> 1}{<.c-br> '}'}"}"
+				" "
+				<c-com> "<a href=\"/tips/about/usage/chapter/1\">"
+			<br>
+			<c-el>
+				<c-tag> "pro-ref-f{<c-el> " params{<c-op> '='}{<.c-br> '{'} chapter{<c-op> ':'} {<c-c> 1}{<.c-br> '}'}"}"
+				" "
+				<c-com> "<a href=\"/tips/chapter/1\">"
+			<br>
+			<br>
+			<c-com> "For external links use <a href=> directly:"
+			<br>
+			<c-tag> "a {<c-el> "href"}{<c-op> '='}{<c-str> 'https://example.com/link'}"
+		<br>
+		"As you can see you pass existing params further or forget them using "
+		<.bordered> "<pro-ref-f>"
+		"."
+		<br>
+		<pro-tip>
+			"Notice "
+			<b> "_local_value"
+			" in url."
+			<br>
+			"Pro-router treats underscore prefixed values as local and never pass it further."
+		<br>
+		<br>
+		<.bordered> "<pro-toggle>"
+		" generates switch on/off element writing to url flag with a given name."
+		<br>
+		<br>
+		<b> "Live examples:"
+		<imba-code url=R.to_path!>
+			<c-tag> "pro-toggle{<c-el> " param{<c-op> '='}{<c-str> 'zoomed'}"}"
+			" {<c-str> "Zoom in/out"}"
+			<br>
+			<c-tag> "pro-toggle{<c-el> " param{<c-op> '='}{<c-str> 'night'}"}"
+			" {<c-str> "Good night"}"
+			<br>
+			<c-tag> "pro-toggle{<c-el> " param{<c-op> '='}{<c-str> 'night'} disabled{<c-op> '='}{<c-c> true}"}"
+			" {<c-str> "Switch disabled"}"
+			<div[d:hcc jc:space-around my:20px us:none h:20px] slot='live'>
+				<pro-toggle.button param='zoomed'> 'Zoom in/out'
+				<pro-toggle.button param='night'> 'Good night'
+				<pro-toggle.button param='night' disabled=true> 'Switch disabled'
+		<br>
+		<br>
+		<.bordered> "<pro-router>"
+		" displays current view."
+		<br>
+		<br>
+		"The simplest application would look like this:"
+		<imba-code file='src/main.imba'>
+			"""
+			imba{<c-op> '.'}mount {<c-tag> 'pro-router'}
+			"""
+		<br>
+		"A bit more complex example:"
+		<imba-code url="/{R.param('subview')}">
+			"""
+			{<c-tag-def> 'my-app'}
+			    {<c-tag> 'self'}
+			        {<c-tag> "pro-ref-f{<c-el> ' view'}{<c-op> '='}{<c-el> 'v'}"} {<c-op> 'for'} v {<c-op> 'in'} {<c-c> 'R'}{<c-op> '.'}views {<c-com> 'render menu'} 
+			        {<c-tag> "pro-router"}                      {<c-com> 'slot for current view'}
+
+			{<c-tag-def> 'view-hello'}
+			    {<c-tag> 'self'} 'Hello World!'
+
+			{<c-tag-def> 'view-another-view'}
+			    {<c-tag> 'self'} 'This is another view.'
+
+			imba{<c-op> '.'}mount {<c-tag> 'my-app'}
+			"""
+			<div[d:vcc h:140px] slot="live">
+				<example-menu[mb:30px]>
+				<{ "example-{R.param('subview')}" }>			
+		<br>
+		<pro-tip>
+			"You can override current view and display another. For example defined by param from url:"
+			<imba-code>
+				<c-tag> "pro-router{<c-el> ' view'}{<c-op> '='}{<c-c> 'R'}{<c-op> '.'}param{<.c-br> '('}{<c-str> 'subview'}{<.c-br> ')'}"
+
+		<br>
+		<br>
+
+tag example-menu
+	<self>
+		<example-pro-ref-f.button params={}> "HELLO"
+		<example-pro-ref-f.button params={ subview: 'another-view' }> "ANOTHER-VIEW"
+
+tag example-pro-ref-f < pro-ref-f
+	def render
+		let link = go || url
+		<self[d:inline].active=(R.to_path! == link) href=link @click.prevent=R.go(link)><slot>
+
+tag example-hello
+	<self> 'Hello World!'
+
+tag example-another-view
+	<self> 'This is another view.'
+
+R.getters.subview = do |v| v || 'hello'
\ No newline at end of file