DEV Community: kyw

Deepseek and ChatGPT can't get this right: How to update a CloudFlare KV pair with metadata

kyw — Mon, 10 Feb 2025 08:26:08 +0000

Current state-of-the-art generative AI was supposed to be able to give me straight answer for this. But ChatGPT and Deepseek kept giving me wrong answers and wasting even more of my time going back and forth than if I had just read the damn documentation myself.

So here is the straight answer from me, a human being, on how to update a specific Cloudflare KV pair along with updated metadata:

const url = `https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/storage/kv/namespaces/<NAMESPACE_ID>/values/<KV_KEY>`;

const formData = new FormData();
formData.append('value', <KV_VALUE>);
formData.append('metadata', JSON.stringify(<KV_METADATA_OBJ>));

const response = await fetch(url, {
   method: 'PUT',
   headers: {
     Authorization: `Bearer <API_TOKEN>`,
   },
   body: formData,
});

const result = await response.json();

console.log(result);

Conclusion

Still no way I'm trusting 'AI'. They don't know what they are doing. GenAI won't get us to AGI and all that. We are doing AI wrong. Also check out my website to discover best movies from Wikipedia nobody else is recommending. That's all. Cheers.

Reimagining User Experience of Markdown Link

kyw — Mon, 20 May 2024 04:52:41 +0000

Introduction

Zuunote aims to make writing in Markdown enjoyable to everyone. This includes technical and non-technical people - and everyone in between. This means crafting a writing experience that feels right to everyone. And this posts documents my balancing act in achieving that when creating and editing links in Markdown.

How to create a link in Markdown

Let's get this out of the way first. This is how a link looks like in Markdown: [Contact us](https://example.com/contact-us)

There are two parts to it:

Brackets []: The text of your link goes in there, in this case Contact us. And,
Parentheses (): The URL goes in there, in this case https://example.com/contact-us.

The brackets [] part comes first, followed by the parentheses () part.

Advantages of creating Markdown links with plain-text characters

The brackets and parentheses can be intimidating and a turn off to a lot of people. But I believe that once you get past that, you are going to experience something in your writing that you never did before.

For example, this is how you would create a link in Google Doc:

Compare to Markdown editors such as Typora:

Confluence can do that too:

Again, I believe once you get past having to enter brackets and parentheses, writing in Markdown will become extremely ergonomic for you.

And one positive side effect is: editing becomes precise too.

I mean, for example, you will run into troubles in Google Doc and Confluence if you want to edit in the beginning of a link's text:

even though you can edit it anywhere in between:

That's a little confusing, right?

This is the fool-proof way to edit link's text in Google Doc:

and in Confluence:

(Note: in Confluence, link creation and modification flows are different. See more)

and in Notion:

But you don't have to struggle like that in Markdown Editors:

(But notice the exploded long url and the inconvenience to copy and select. More on this below.)

No surprises there! Once we knew that brackets [] encloses link's text, we can precisely edit the texts anywhere within them.

However, even with this added ergonomics and precision from Markdown, I believe there are still areas we can improve.

UX issues of Markdown links

Markdown editors such as Typora that offers live-preview without split-pane offer an ergonomic way to create links. However, when it comes to editing them, it's not as ergonomic and pleasant as it's precise.

Notice the jarring shift in your content when you focus on a link with a super long URL.

Nota, a Markdown editor for Mac, solves it by initially showing an icon as a placeholder:

But still doesn't avoid the content shift when cursor enters the parentheses:

Additional to the content shift, copying and editing the long URL are not easy to everyone:

Zuunote

Zuunote's guiding principle is to meet everyone halfway - everyone who is using Google Docs and Microsoft Words, and everyone who is using Notion, Confluence, Typora, and Obsidian.

Below is how I meet Markdown links halfway for everyone.

Creating links

Everything is just plain-texts. Boring but good and accessible.

Entering links

Here, I adopt the action buttons that you see in Google Docs and Notion, and enclose them with parentheses as seen in a vanilla Markdown link, which means link's Markdown syntax is still being enforced:

This implementation not only avoids the jarring content shift, but most importantly it's functional and delightful to everyone.

Edit link's URL

Clicking the edit button displays an input field, in which you can use familiar keyboard shortcuts(or mouse clicks) to quickly select all, copy, or paste.

Things still flow and act like plain-text but now with added niceties you see in places like Google Doc and Notion.

Copy link's URL

Copy URL by clicking a button rather than carefully selecting the text.

Remove links

Conclusion

It seems to me that every text editor caters solely to a particular group of people. What if there's a text editor that all groups of people can equally enjoy? That's the goal of Zuunote. And I hope it shows here through the way it implements links. But I'm way in over my head. So please send me feedbacks at hello@zuunote.com if you want. Or just join the waitlist.

Thank you for your attention and time. Take care.

UX Case Study: Markdown Heading

kyw — Sat, 27 Apr 2024 09:11:23 +0000

To create a heading in Markdown, at the start of a line, you put a hash character # followed by a space:

To create a second level heading, you put two hash characters, and so on:

OK, all that's good to know, I guess. But so far I only see a bunch of weird characters floating around my texts that I was told would format them in a certain way. But I don't actually see them.

Now, one way of showing them as what they really are is by highlighting the Markdown syntax characters # and *:

Now I can see my italic text being...italic, but I still don't see my H1 heading. Surely it can't be the same size as my body text, right?

Well, ...drum roll...

It's the split-pane!

With split-pane, I can finally see my big phat H1 heading!

Split-pane was(and is) everywhere:

(Dillinger editor)

(iA Writer)

(Inkdrop)

(VSCode)

However, under this setup, I would have to shift my attention, from my editor on the left side, to the split-pane on the right side, and again. This would be exhausting.

What if we got rid of the split-pane, but we still could preview our stuff as we write? Sure we can!

A step in that direction can be seen in TOAST UI editor:

(Inkdrop)

You can literally add or delete the hash characters to get to your desired level of heading. And the coolest part is: you can see the heading's size adjusts right there in real-time!

Very nice!

Some editors don't seem to take this real-time visual feedback all the way though. Examples below show the italic text in the heading is formatted in the editor in real-time, but not the heading itself:

(iA Writer)

(Notable)

Anyway, I can't help but notice the Markdown syntax characters # and * are still sticking out even though technically we are already in preview mode while we write. In other words, we are not exactly WYSIWYG yet.

Now, let's take a look at a few editors that might take us there: writing Markdown in a strictly WYSIWYG fashion without a split-pane.

Here is how Notion do it:

No more # and * sticking out! We are finally in the realm of WYSIWYG!

Same thing in Atlassian's Confluence:

In both of them, users can easily create headings and italic texts by entering their respective Markdown syntax characters. This is a user flow and a mental model we have been accustomed to in every editor that's mentioned here so far.

But here is the thing: when it comes to editing, users are forced to switch to an entirely different flow and mental model.

For example, to change a heading's level in Notion, you have to double click to select a text in order to bring up a floating toolbar where you will find and select the type of heading you want:

Similarly, in Confluence:

Sure, keyboard shortcuts are available. But they are also an opposing user flow and mental model. They can complement the main flow but not replace it.

At this point, we can form a first principle for a Markdown editor: adding and deleting Markdown syntax characters is each a cause-and-effect that's inextricably linked to each other.

We can observe this principle in the split-pane world:

Entering and deleting characters has been a part and parcel in online writing and editing since the advent of personal computing. If it's possible to enter certain characters to create certain UI element, it should be possible as well to do the reverse - editing the characters that you have entered - to edit the said UI element.

As of this writing, there are only a handful of editors that seem to follow this principle. Let's take a look.

Marktext editor:

But the principle doesn't apply to the heading which can only be changed with keyboard shortcuts.

Here is Typora editor:

Unlike the italic text, users don't get instant visual feedback when creating heading. And like Marktext, editing heading can be done only with keyboard shortcuts.

The closest editor that follows our first principle is Obsidian editor:

That's what I'm talking about!

A minor thing to point out there is the body text becomes italic too when you delete the closing asterisk of the italic text in the heading.

And finally here is a Markdown editor I'm working on:

Conclusion

All modern Markdown editors allow us to adopt a user flow and a mental model in which we can enter Markdown syntax to create UI elements such as headings and italic text. But, in almost all of them, the reverse is not possible - to edit the UI elements, you are forced to adopt an entirely different flow and model.

This post was a journey in search of my ideal editor: a place where visual feedback is immediate from an action as singular as entering and removing a character, and a place where you can see, and feel, every pulse of your written thoughts.

How to build an interactive image for your WYSIWYG editor

kyw — Sat, 27 Jan 2024 10:43:57 +0000

Who will find this post useful

If you are building a WYSIWYG editor and are using Prosemirror libary or Tiptap(which is built on top of Prosemirror), and you would like to offer custom editing experiences for your users' images.

Introduction

In some WYSIWYG editors, after you have inserted an image and if you focus on it, a toolbar will show up with a few action buttons that can do things like change the alignment of the image and its alt text.

Fig. Atlassian's Confluence offers more complicated controls on the images.

Fast forward to now, I'm building a Markdown-based WYSIWYG editor and I found myself wanting to offer users some capabilities to edit their images too. But I had no idea how to begin building it. Google returned no answers and no one could shine me some lights when I was at my wit’s end. I got anxious from being stuck in a rut for days.

And that’s why I’m writing this guide — a guide I wish had existed.

After countless of trial-and-error and console.log, my vision became a reality:

In this article, I will share all the critical knowledge I'd learned the hard way. We will focus on building a similar toolbar specifically for users to replace their images. At the end of this post, you will be able to apply what you have learned to build your own interactions such as resizing the image.

Here is the source code and demo of what we will be building:

In the demo, you can click the View editor data button to view the editor's JSON data to confirm your changes.

Okay let's do this.

Define schema for your image

First things first, our images need a "schema". Schema is where we declare about our images what attributes are allowed, whether they flow inline or not, are they selectable, and more which don't concern us here.

You can find the schema in Image.js file:

    {
      attrs: {
        src: {
          default: '',
        },
      },
      inline: true,
      content: 'text*',
      marks: '',
      group: 'inline',
      atom: true,
      selectable: true,
      parseDOM: [
        {
          tag: 'img',
          getAttrs: (dom) => {
            return {
              src: dom?.getAttribute('src'),
            };
          },
        },
      ],
      toDOM: (node) => {
        return [
          'img',
          {
            class: 'image',
            ...node.attrs,
            src: node.attrs.src,
          },
          0,
        ];
      },
    }

What we are saying there is that our image:

Has a src attribute with default value as empty string if it wasn't provided — attrs.src.default
Is to flow inline, which is the default behavior not only in HTML but also in Markdown spec — inline: true
Can only contain text nodes which themselves are inline. Can't be empty here — content: text*
Don't allow any marks such as bold — marks: ""
Belongs to the inline group — group: inline
Is a leaf node. Apparently, we can't do without this — atom: true
Is selectable — selectable: true
Tag is img when parsing, for example during pasting — parseDom
DOM is structured in a certain way when we create it. Not important here since we will construct the structure in the "node view" which I will show below — toDom

Here is one of the things I found out the hard way: Don't set draggable: true in the schema! Otherwise, for some reasons I still don't know, the input field wouldn't be as responsive. However, it would still be draggable. You can verify this in the demo by first selecting the image, then drag and drop it somewhere else in the editor, then click the "View editor data" button.

Node view

"Node view" is what you need if you want a node with custom interfaces to have behaviors that are orchestrated by you. That sounds like what we are trying to do here.

You can find our node view in image-nodeview.js file. Here it is at the highest level:

class ImageView {
  constructor(node, view, getPos) {
    this.getPos = getPos;
    this.view = view;
    this.node = node;

    // this.dom is your parent container. Create and append your interactive elements to it here or
    // anywhere in this class by accessing this.dom again
  }

  // return true to tell editor to ignore mutation within the node view
  ignoreMutation() {
    return true;
  }

  // return true to stop browser events from being handled by editor
  stopEvent(event) {
    return true;
  }

  // this is called when user has selected the node view
  selectNode() {}

  // this is called when user selected any node other than the node view
  deselectNode(e) {}

  // update the DOM here
  update(node) {}

  // clean up when image is removed from editor
  destroy() {}
}

This class conforms to the interface of a node view object. I use class here to, not only return the node view object when we instantiate it later, but also to store some useful values(e.g. getPos, view, node) to properties that we can access in any method in the class.

Let's see what each of the methods in the class can do for us in achieving our goal here.

constructor

Here is where I construct the custom interfaces of my image with good 'ol document.createElement and appendChild. Just make sure that all of them is housed under dom which is your top-most container element.

this.dom = document.createElement("div");
this.img = document.createElement("img");

this.dom.appendChild(this.img);

The initial values of a particular image's attributes such as src can be found in node.attrs.

constructor(node, view, getPos) {
    // ...

    this.img = document.createElement("img");
    this.img.src = node.attrs.src;

    // ...
}

Another thing I learned the hard way is: Don't use contentDOM to house your custom interfaces because Prosemirror will jump in and manage for you which would produce weird results that I had to spend hours to resolve to make everyone happy. So just put everything in this.dom and you will get full control and things will work as you expect.

ignoreMutation

We will return true here to tell editor to ignore any DOM changes we make in our node view, otherwise things will get willy willy wonky.

ignoreMutation() {
    return true;
}

stopEvent

If we return true here, means that we are stopping any browser events originated from our node view from being handled by the editor. And this is what I do to, again, avoid wonky response from the editor. The only time to return false here is when I want to inform editor that user has selected the node view. This works in tandem with the following section.

stopEvent(event) {
    // let this event through to editor if it's coming from img itself
    if (event.target.tagName === 'IMG') return false;

    // otherwise, block all events at the node view level
    return true;
}

selectNode

Since we are passing through events from img tag to editor, this function will run when editor has detected our node view has been selected.

This is where I add a CSS class for styling and bind a event handler to handle some stuff.

 selectNode() {
    // add a class on the container for conditional styling on its childs
    this.dom.classList.add('ProseMirror-selectednode');

    // bind a click event handler to the document object to detect when user has clicked outside of the node view
    document.addEventListener('click', this.outsideClickHandler);
  }

 outsideClickHandler(event) {
    if (this.isEditing) {
      this.isEditing = false;
      return;
    }
    // exit if still inside image
    if (this.dom.contains(event.target)) return;

    document.removeEventListener('click', this.outsideClickHandler);

    this.dom.classList.remove('ProseMirror-selectednode');
  }

This outside-click detector does 3 things:

If user is still editing, reset isEditing property to false and exit early.
Exit early as well if the click wasn't outside of the node view.
If the click was outside of node view, clean up the event handler on document and remove the CSS class added in selectNode.

deselectNode

This function runs when editor has detected user has selected a node other than our node view. This place is useful to reverse the effects applied in the selectNode.

But seems to me it would run whenever I interact with the custom interface of my image node view. To work around that, I introduced a isEditing boolean check here to exit this function if its value is true. And once all event handlers have run after each interaction(stopEvent -> deselectNode -> outsideClickHandler()), I set it back to false automatically via setTimeout.

deselectNode() {
    if (!this.isEditing) {
      this.dom.classList.remove('ProseMirror-selectednode');
    }

    setTimeout(() => {
      this.isEditing = false;
    }, 0);
}

update

This is where I update the actual DOM after I have dispatched(there is a section about this below) a specific change to the editor.

update(node) {
    if (node.type.name !== 'image') return false;

    this.node = node;

    for (const [name, value] of Object.entries(node.attrs).filter(Boolean)) {
      this.img.setAttribute(name, value);
    }

    return true;
}

destroy

Do clean-up here when the node view is removed from the editor. For example, remove any event listeners on document or window, and set this.dom to null to free up the memory.

 destroy() {
    document.removeEventListener('click', this.outsideClickHandler);
    this.dom = null;
}

How to dispatch changes to editor

Every change during editing needs to be dispatched to the editor so that it's reflected when we output for our editor's data.

In this case, when user has replaced an image, we will dispatch the new src value to the editor. The way we do that in a node view is with this snippet:

this.view.dispatch(
  this.view.state.tr.setNodeMarkup(this.getPos(), null, {
    ...this.node.attrs,
    src: /* value of new src here */,
  }),
);

You can do this in any event handler anywhere in the class on any interactive elements of your node view. In this case, I do it when user submit the form with a new image URL:

toolbarForm.addEventListener("submit", (event) => {
  event.preventDefault();

  const formData = new FormData(toolbarForm);

  const attrs = {};

  for (let [name, value] of formData) {
    attrs[name] = value;
  }

  this.view.dispatch(
    this.view.state.tr.setNodeMarkup(this.getPos(), null, {
      ...this.node.attrs,
      ...attrs,
    }),
  );
});

Click the View editor data button to verify the latest src value.

Wiring up the node view

Finally, now that we have created a node view for our image, we need to tell our editor to use it when it's rendering images.

In Editor.js file, you can see we do just that with the nodeViews property:

new EditorView(/* document.querySelector("#app") */, {
  // state: this.state,
  // attributes: { spellcheck: false },
  nodeViews: {
    image(node, view, getPos) {
      return new ImageView(node, view, getPos);
    },
  },
});

And that's all I got! Please leave a comment if you know there's a better way to all this :)